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Abstract 

Modern microcontrollers provide an amazingly diverse selection of hardware peripherals, 
all within a single chip. One needs to provide a small amount of supporting hardware 
to power the chip and connect its peripheral devices to the signals of interest and, when 
powered up, these devices need to be configured and monitored by a suitable firmware 
program. 

These notes focus on programming the 28-pin PIC18F26K22 microcontroller and its 40- 
pin PIC18F46K22 sibling, the 16-bit PIC24FV32KA302 and the 8-bit AVR ATmega328P. 
These microcontrollers are all available in plastic DIP packages, can be run from a 5 volt 
supply, and can be built into very simple prototype hardware. 

A number of example programs, in the Forth language, are provided to illustrate the use 
of some of each microcontroller’s peripheral devices. The examples cover the very simple 
“flash a LED” exercise through to driving a character-based LCD via its 4-bit parallel 
interface. Communication with SPI and I 2 C devices is also covered, with a common set 
of words being used to abstract away the differences between microcontrollers in terms of 
detailed bits and registers. 
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1 A selection of microcontrollers 

Over the past couple of decades, microcontrollers have evolved to be cheap, powerful 
computing devices that even Mechanical Engineers can use in building bespoke instru¬ 
mentation for their research laboratories. Typical tasks include monitoring of analog 
signals, sensing pulses and providing timing signals. Of course these things could be done 
with a modern personal computer connected via USB to a commercial data acquisition 
and signal processing system but there are many situations where the small, dedicated 
microcontroller, requiring just a few milliamps of current, performs the task admirably 
and at low cost. 

Modern microcontrollers provide an amazingly diverse selection of hardware peripherals, 
all within a single chip. One needs to provide a small amount of supporting hardware 
to power the chip and connect its peripheral devices to the signals of interest and, when 
powered up, these devices need to be configured and monitored by a suitable firmware 
program. These following sections provide an introduction to the details of doing this with 
an 8-bit Microchip PIC18F26K22 or PIC18F46K22 microcontroller, a 16-bit Microchip 
PIC24FV32KA302 microcontroller and an 8-bit Atrnel ATmega328P microcontroller, all 
programmed with the FlashForth version 5 interpreter [1] . 

Within each family of Microchip or Atrnel microcontrollers, the individual microcontroller 
units (MCUs) all have the same core, i.e. same instruction set and memory organisation. 
Your selection of which MCU to actually use in your project can be based on a couple 
of considerations. If you are on a tight budget and will be making many units, choose 
an MCU with just enough functionality, however, if convenience of development is more 
important, choose one with “bells and whistles”. For this tutorial guide, we will value 
convenience and so will work with microcontrollers that have: 

• a nice selection of features, including a serial port, several timers and an analog-to- 
digital converter. See the feature list and the block diagram of the PIC18F26K22 
and PIC18F46K22 MCUs on the following pages. 

• a 28-pin narrow or 40-pin D1L package, which is convenient for prototyping and has 
enough I/O pins to play without needing very careful planning. 

• an ability to work as 3.3V or 5V systems. 

• a pinout as shown at the start of the datasheets (books) [2, 3, I]. You will be reading 
the pages of these books over and over but we include the following couple of pages 
from the PIC18F22K26/PIC18F46K22 datasheet to give an overview. 

• an internal arrangement that is built around an 8-bit or 16-bit data bus. 

• the “Harvard architecture” with separate paths and storage areas for program in¬ 
structions and data. 

We won’t worry too much about the details of the general-purpose registers, the internal 
static RAM or the machine instruction set because we will let the FlashForth interpreter 
handle most of the details, however, memory layout, especially the I/O memory layout 
is important for us as programmers. The peripheral devices, which are used to interface 
with the real world, are controlled and accessed via registers in the data-memory space. 
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Microchip_PIC18(L)F2X/4XK22 

28/40/44-Pin, Low-Power, High-Performance 
Microcontrollers with XLP Technology 


High-Performance RISC CPU: 

• C Compiler Optimized Architecture: 

- Optional extended instruction set designed to 
optimize re-entrant code 

• Up to 1024 Bytes Data EEPROM 

• Up to 64 Kbytes Linear Program Memory 
Addressing 

• Up to 3896 Bytes Linear Data Memory Address¬ 
ing 

• Up to 16 MIPS Operation 

• 16-bit Wide Instructions, 8-bit Wide Data Path 

• Priority Levels for Interrupts 

• 31-Level, Software Accessible Hardware Stack 
•8x8 Single-Cycle Hardware Multiplier 

Flexible Oscillator Structure: 

• Precision 16 MHz Internal Oscillator Block: 

- Factory calibrated to ± 1% 

- Selectable frequencies, 31 kHz to 16 MHz 

- 64 MHz performance available using PLL - 
no external components required 

• Four Crystal modes up to 64 MHz 

• Two External Clock modes up to 64 MHz 

• 4X Phase Lock Loop (PLL) 

• Secondary Oscillator using Timerl @ 32 kHz 

• Fail-Safe Clock Monitor: 

- Allows for safe shutdown if peripheral clock 
stops 

- Two-Speed Oscillator Start-up 

Analog Features: 

• Analog-to-Digital Converter (ADC) module: 

- 10-bit resolution, up to 30 external channels 

- Auto-acquisition capability 

- Conversion available during Sleep 

- Fixed Voltage Reference (FVR) channel 

- Independent input multiplexing 

• Analog Comparator module: 

- Two rail-to-rail analog comparators 

- Independent input multiplexing 

• Digital-to-Analog Converter (DAC) module: 

- Fixed Voltage Reference (FVR) with 1,024V, 
2.048V and 4.096V output levels 

- 5-bit rail-to-rail resistive DAC with positive 
and negative reference selection 

• Charge Time Measurement Unit (CTMU) module: 

- Supports capacitive touch sensing for touch 
screens and capacitive switches 


Extreme Low-Power Management 
PIC18(L)F2X/4XK22 with XLP: 

• Sleep mode: 20 nA, typical 

• Watchdog Timer: 300 nA, typical 

• Timerl Oscillator: 800 nA @ 32 kHz 

• Peripheral Module Disable 

Special Microcontroller Features: 

• 2.3V to 5.5V Operation - PIC18FXXK22 devices 

• 1.8V to 3.6V Operation - PIC18LFXXK22 devices 

• Self-Programmable under Software Control 

• High/Low-Voltage Detection (HLVD) module: 

- Programmable 16-Level 

- Interrupt on High/Low-Voltage Detection 

• Programmable Brown-out Reset (BOR): 

- With software enable option 

- Configurable shutdown in Sleep 

• Extended Watchdog Timer (WDT): 

- Programmable period from 4 ms to 131s 

• In-Circuit Serial Programming™ (ICSP™): 

- Single-Supply 3V 

• In-Circuit Debug (ICD) 

Peripheral Highlights: 

• Up to 35 I/O Pins plus 1 Input-Only Pin: 

- High-Current Sink/Source 25 mA/25 mA 

- Three programmable external interrupts 

- Four programmable interrupt-on-change 

- Nine programmable weak pull-ups 

- Programmable slew rate 

• SR Latch: 

- Multiple Set/Reset input options 

• Two Capture/Compare/PWM (CCP) modules 

• Three Enhanced CCP (ECCP) modules: 

- One, two or four PWM outputs 

- Selectable polarity 

- Programmable dead time 

- Auto-Shutdown and Auto-Restart 

- PWM steering 

• Two Master Synchronous Serial Port (MSSP) 
modules: 

- 3-wire SPI (supports all 4 modes) 

- I 2 C™ Master and Slave modes with address 
mask 


© 2010-2012 Microchip Technology Inc. 
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PIC18(L)F2X/4XK22 


FIGURE 1-1: 


PIC18(L)F2X/4XK22 FAMILY BLOCK DIAGRAM 


Data Bus<8> 



DAC 
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10-bit 
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Note 1: RE3 is only available when MCLR functionality is disabled. 

2: 0SC1/CLKIN and OSC2/CLKOUT are only available in select oscillator modes and when these pins are not being used as digital I/O. 

Refer to Section 2.0 “Oscillator Module (With Fail-Safe Clock Monitor)” for additional information. 

3: Full-Bridge operation for PIC18(L)F4XK22, half-bridge operation for PIC18(L)F2XK22. 
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2 Development boards 

This tutorial is based around simple support hardware for each of the microcontrollers. 
If you don’t want to do your own soldering, there are easy-to-buy demonstration boards 
available as a convenient way to get your hardware up and going. If you are a student of 
mechatroncis, however, you must eventually design and build your own hardware. The 
strip-board versions are aimed at you. 

2.1 PIC18 family boards 

Here is a picture of PICDEM 2 PLUS with PIC18F46K22-I/P in the 40-pin socket (Ul) 
and running the LCD, as described in Section 16. We’ll make use of the serial RS-232 
interface (MAX232ACPA, U3) to both program Forth application and to communicate 
with running applications. Other conveniences include on-board LEDs, switches, a po¬ 
tentiometer (RAO) and I 2 C devices, such as a TC74 temperature sensor (U5), just below 
the MCU and a 24LC256 serial EEPROM (U4). Initial programming of the FlashForth 
system into the MCU can be done via jack J5 (labelled ICD in the lower left of the 
photograph) with a Microchip MPLAB-ICD3, PICkit3, or similar device programmer. 



If you want a homebrew system, you can build a minimal system on strip-board that 
works well. One of the nice things about such a strip-board construction is that you 
can easily continue construction of your bespoke project on the board and, with careful 
construction, your prototype can provide years of reliable service. 
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Here is a detailed view of the home-made demo board with PIC18F26K22 in place. This 
board is suitable for the exercises in this guide. A separate regulator board is to the 
left and a current-limited supply provides the input power. The board is simple to make 
by hand, with header pins for the reset switch and connections to the LEDs. The 4-pin 
header in the foreground provides an I 2 C connection. The ICSP header is only needed to 
program FlashForth into the MCU, initially. All communication with the host PC is then 
via the TTL-level serial header (labelled FTDf-232) at the right. Beyond the minimum 
required to get the microcontroller to function, we have current-limiting resistors and 
header pins on most of the MCU’s I/O pins. This arrangement is convenient for exercises 
such as interfacing to the 4x3 matrix keypad (Section 9). 

The schematic diagram of this home-brew board is shown on the following page. Note that 
there is no crystal oscillator on the board; the internal oscillator is sufficiently accurate for 
asynchronous serial port communication. Note, also, the lk resistors in the TX and RX 
nets. These limit the current going through the microcontroller pin-protection diodes in 
the situation where the microcontroller board is unpowered and the FTDI-232 cable is still 
plugged in to your PC. This will happen at some point and, without the current-limiting 
resistors, the FTDI cable will power the microcontroller, probably poorly. 
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2.2 AVR and PIC24 boards 

The Eleven from Freetronics, shown in the left half of the following photograph, is an 
Arduino-compatible board carrying an ATmega328P microcontroller. This is a conve¬ 
nient piece of hardware with many prototype-friendly boards available to plug into the 
headers around the periphery of the board. Although these boards come with the Arduino 
bootloader preprogrammed into the ATmega328 microcontroller, the standard AVR 6-pin 
programming header on the right-hand end of the board (in the photo) can be used to 
reprogram the microcontroller with the FlashForth interpreter. Power and serial port 
access is through the USB connector at the left. 

If you want an almost-no-solder option for prototyping with the PIC24FV32KA302, Mi¬ 
crochip provide the Microstick 5V for PIC24K-series. As shown in the following photo¬ 
graph, this is convenient in that it includes a programmer on-board and can be plugged 
into a bread-board. The power supply and flash programming access is provided through 
the USB connector on the left of the board while the serial port connection is via the 
6-pin connector on the right-end of the board. 
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Building a minimal board, by hand, for any of these processors is fairly easy and strip- 
board versions for each is shown in the following photograph. The left-hand board is for 
the PIC18F26K22, before all of the extra protection resistors were added. In this state, 
FlashForth can already be used on this board for nearly all of the exercises in the following 
sections. Schematic diagrams for the PIC24 and AVR microcontrollers are shown on the 
following pages. 



Each of the boards has headers for (1) power, (2) in-circuit serial programming, (3) I2C 
communication and (4) TTL-level-232 serial communication. The ATmega328 board on 
the right has a few more protection resistors installed and has an 16 MHz crystal because 
serial-port communication was found to be unreliable using the internal oscillator. 
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AVR ATmega328 not-quite minimal demo board 
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3 FlashForth 

Forth is a word-based language, in which the data stack is made available to the pro¬ 
grammer for temporary storage and the passing of parameters to functions. Everything 
is either a number or a word. Numbers are pushed onto the stack and words invoke func¬ 
tions. The language is simple enough to parse that full, interactive Forth systems may 
be implemented with few (memory) resources. Forth systems may be implemented in a 
few kilobytes of program memory and a few hundred bytes of data memory such that it 
is feasible to provide the convenience of a fully interactive program development on very 
small microcontrollers. 

The classic beginners book by Brodie [ ] is available online 1 , as is Pelc’s more recent 
book [6] 2 . A more detailed reference is published by Forth Inc [ ]. These books are biased 
toward Forth running on a personal computer rather than on a microcontroller, however, 
they are a good place to start your reading. For an introductory document that is specific 
to FlashForth, see the companion report [ ]. 

FlashForth [1] for the PIC18, PIC24 and ATmega families of microcontrollers is a full 
interpreter and compiler that runs entirely on the microcontroller. It is a 16-bit Forth with 
a byte-addressable memory space. Even though there are distinct memory types (RAM, 
EEPROM and Flash) and separate busses for data and program memory in these Harvard- 
architecture microcontrollers, FlashForth unifies them into a single 64kB memory. 

Above working in assembler, FlashForth does use some resources, both memory and 
compute cycles, but it provides such a nice, interactive environment that these costs are 
usually returned in convenience while tinkering with your hardware. Forth programs are 
very compact so you will have less code to maintain in the long run. The interpreter 
can also be available to the end user of your instrument, possibly for making parameter 
adjustments or for making the hardware versatile by having a collection of application 
functions present simultaneously in the firmware, with the user selecting the required 
function as they wish. 


3.1 Getting FlashForth and programming the MCU 

FlashForth is written in assembler, with one program source for each of the microcontroller 
families and a number of Forth text hies to augment the core interpreter. The source code 
can be downloaded from SourceForge at the URL 
http://sourceforge.net/proj ects/flashforth/ 

There, you will see that you can get a packaged release or you can clone the git repository. 

To build from this source, you will need to start up your integrated development environ¬ 
ment (be it MPLAB, MPLAB-X or AVR Studio), open the program source and conkg 
hies in this IDE and edit the conhg hle(s) match your selection of oscillator. There are 
other options to customize but the choice of oscillator is the main one. The machine 
code can then be assembled and programmed into your microcontroller with a suitable 
device programmer (PICkit3, ICD3, STK500, AVRISP Mkll, ...). Once programmed with 


Tttp : //home.iae.nl/users/mhx/sf.html and http://www.forth.com/starting-forth/ 

2 http://www.mpeforth.com/ 



3 FLASHFORTH 


15 


FlashForth, and mounted in a board that provides power and serial communications as 
described in the previous section, you will be ready to interact with FlashForth via a 
serial terminal or shell. 

3.2 Building for the PIC18F26K22 or PIC18F46K22 

For our minimal system with either the PIC18F26K22 or PIC18F46K22 microcontroller, 
we elect to use the internal (16 MHz) oscillator multiplied by 4 by the PLL. Within the 
MPLAB-X development environment, we started a new standalone project to build our 
FlashForth program that will use the microcontroller’s UART serial port as the OPERA¬ 
TOR communications channel. Following the prompt screens, we selected a specific pro¬ 
cessor (PIC18F26K22), our hardware tool (ICD3), and the compiler toolchain (mpasm). 

To build the actual machine code that will be programmed into the flash memory of the mi¬ 
crocontroller, it is sufficient to assemble the principal source hie ff-picl8. asm along with 
the configuration (or header) hies picl8f-main. cfg, picl8fxxxx. cfg, pl8f2x4xk22. cfg, 
and use the linker script FF_0000.1kr. The source hie and conhg hies can be found in 
the directory picl8/src/, while the linker hie is in picl8/lkr/. There may be other 
configuration hies already added to the project but you can ignore them. 

We edited the processor-specihc conhg hie, pl8f2x4xk22. cfg, writing “PLLCFG = ON” to 
have the PLL enabled (giving Fosc — 64 MHz), enable the watchdog timer with a 1:256 
postscale (WDTPS = 256) to get approximately a 1 second time-out period, and enable the 
external reset capability (MCLRE = EXTMCLR). Being able to reset the microcontroller by 
bringing the MCLR pin low is something that we hnd convenient when tinkering with new 
hardware. We set the hnal line as 
#define PLL ENABLE 

We needed to edit the pic 18f-main. cfg hie only to set the system clock frequency as 
constant clock=cP 64000000 L With this clock frequency, the microcontroller requires 
approximately 7 mA current while the interpreter is running and waiting for input. 

There are many other options for customizing the FlashForth program in this hie, however, 
the default parameters are fine for the hrst build of our minimal system. To see your 
options for all of the conhguration bits for your specihc microcontroller, it is convenient 
to open the MPLAB-X view from the main menu: Window —y PIC Memory Views —y 
Configuration Bits. 

With the specihc microcontroller selected for the project, the conhg hie picl8fxxxx. cfg 
will automatically select the appropriate MPLAB include hie for the microcontroller, be 
it pl8f 26k22. inc for the 28-pin chip on the home-made board or pl8f 46k22. inc for the 
40-pin chip on the PICDEM 2 PLUS board. If the build process complains of not being 
able to hnd the MCU-specihc include hie, you may need to adjust the case-sensitivity 
of the assembler. This check box can be found in the Project Properties dialog, under 
“General Options” for the mpasmx assembler, as shown in the following screen shot. 



3 FLASHFORTH 


16 



The following image shows the result of building in Microchip’s MPLAB X IDE. The lower 
left frame in the MPLAB-X window shows the MCU resources used. With 426 bytes of 
SRAM used (another 3470 free) and 8948 bytes of program memory used (56588 free), 
For the PIC18F26K22 MCU, FlashForth occupies only about one-seventh of the micro¬ 
controller’s program memory. Most of the memory is available for the your application. 
For more details on the SRAM memory map, see “The Hitchhiker’s Guide to FlashForth 
on PIC18 Microcontrollers”. There, Mikael Nordman has provided a memory map that 
shows how the SRAM memory is allocated within the FlashForth system. 



The final step is to program the FlashForth machine code into the flash memory of the 
microcontroller, using whatever device programmer you happen to have plugged into your 
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development system. The Dashboard view in the screen shot above shows that we have 
seleted to use of the MPLAB ICD3. 


3.3 Building for the PIC24FV32KA302 

Building for the 16-bit PIC24 family is similar process. This time look for the source 
code hies in the pic24/ subdirectory. There are fewer conhg hies but you may need to 
customize the closest one for your particular processor. Here is the required text in the 
p24fk_conf ig. inc hie for our PIC24FV32KA302-I/SP microcontroller using its internal 
8 MHz oscillator with 4x PLL and installed on the home-made minimal board: 

;;; Device memory sizes. Set according to your device. 

;;; You can increase the addressable flash range be decreasing the addressable ram. 

;;; Below is the setting for max amount of ram for PIC24FV32KA302 
.equ FLASH_SIZE, 0x5800 ; Flash size in bytes without the high byte 

; See program memory size in the device datasheet. 

.equ RAM_SIZE, 0x0800 ; Ram size in bytes 

.equ EEPR0M_SIZE, 0x0200 ; Eeprom size 

; For some reason the normal config macros did not work 

.pushsection _FOSCSEL.sec, code 

.global _F0SCSEL 

_F0SCSEL: .pword FN0SC_FRCPLL 

.popsection 

; Start additions for FF Tutorial board with PIC24FV32KA30x 

.pushsection _FOSC.sec, code 

.global _F0SC 

_F0SC: .pword 0SCI0FNC_0FF 

.popsection 

.pushsection _FICD.sec, code 

.global _FICD 

_FICD: .pword ICS_PGx2 

.popsection 
; End additions 

.equ FREQ_0SC, (8000000*4) ;Clock (Crystal)frequency (Hz) 

Once programmed, FlashForth uses 542 of the microcontroller’s 2048 bytes of SRAM 
and 4544 of the MCU’s 11264 words of Flash memory. This leaves most of the memory 
for your Forth application program. Although this appears to be a lot less than that 
available in the PIC18F26K22 MCU, this 16-bit MCU has lots of interesting hardware. 
With instruction cycle frequency of 16 MHz and the interpreter waiting for input, the 
current consumption is 7.5 mA, approximately the same as for the 8-bit PIC18F26K22. 

3.4 Building for the ATmega328P 

Assembling the FlashForth program within the AVR Studio IDE is fairly simple but Mike 
Nordman has made life even simpler for users of Arduino-like hardware by providing a 
prebuilt .hex hie that can be programmed into the ATmega328P. Here is the command 
for doing so with avrdude on a Linux PC. 

$ sudo avrdude -p ra328p -B 8.0 -c avrisp2 -P usb -e \ 

-U efuse:w:0x07:ra \ 

-U hfuse:w:0xda:ra \ 

-U Ifuse:w:Oxff:ra \ 

-U flash:w:ff_uno.hex:i 
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The fuses are set to use the 16 MHz crystal on the Arduino-like board. 


4 Interacting with FlashForth 

Principally, interaction with the programmed MCU is via the serial port. For the PIC mi¬ 
crocontrollers, settings are 38400 baud 8-bit, no parity, 1 stop bit, with software (Xon/X- 
off) flow control. For the ATmega328P (as programmed above), the baud rate is 9600. 

The FlashForth distribution includes a couple of shell programs that are programmed 
with some knowledge of the FlashForth interpreter. The f f-shell. py program is written 
in Python and allows interaction with the microcontroller via a standard command shell. 
It depends on a Python interpreter and the pyserial extension being installed on your PC. 
The ff-shell.tel is a GUI program that displays the interaction text in a dedicated 
window on your PC. It requires the Tcl/Tk interpreter which is usually part of a Linux 
environment but it may be installed on MS-Windows or MacOSX as well. 

The following images shows the ff-shell.tel window just afer sending the content of 
the flash-led.txt hie to the PIC18F26K22. The device name of /dev/ttyUSBO on the 
status line refers to the USB-to-serial interface that was plugged one of the PC’s USB 
ports. It is convenient to start the program with the command 

$ sudo ./ff-shell.tel 

If necessary, you can adjust the communication settings by typing new values into the 
entry boxes and pressing Enter to repoen the connection. 


peterj@helmholtz ~/pic_work/flash-forth/ff-shell S sudo ./ff-shell.tel 
Serial channel is open as file6 


File Log Micro Help 



BP FlashForth PIC18F26K22 07.06.2015 

-flash-led -flash-led ? 
marker -flash-led ok<$,ram> 

$ff8a constant latb ok<$,ram> 

$ff93 constant trisb ok<$,ram> 

init 1 trisb mclr ; \ want RB0 as output ok<$,ram> 
do_output latb c@ 1 xor latb c! ; \ toggle RB0 ok<$,ram> 
wait #500 ms ; ok<$,ram> 

main init begin do_output wait again ; ok<$,ram> 
main 


Serial Port 

Device: /dev/ttyUSBO 


Speed: 38400 ParityAndBits: n,8,l Hand Shake: xonxoff State: open 


As you type characters into the main text widget, ff-shell.tel intercepts them and 
sends them, one at a time, via the serial port to the microcontroller. As the microcontroller 
sends characters back, the program Liters them and displays them in the text widget. 
There is also a send-hle capability that will send the text from the hie as fast as it can, 
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without overwhelming the microcontroller. The Python program ff-shell.py has a 
special command #send to start the equivalent process. 

If you have sent the microcontroller off to do a repetitive task, such as flashing the LED 
indefinitely, you can regain the interpreter’s attention by sending a Control-0 character. 
The interpreter aborts the execution of the current word and does a software restart. 
After initialization, the interpreter announces that it is ready to begin. Subsequently 
pressing Enter will get the ok response, as shown below. The warm restart action is also 
available from the menu as Micron-Warm Restart. 




-flash-led -flash-led ? 
marker -flash-led ok<$,ram> 
$ff8a constant latb ok<$,ram> 


main S FlashForth PIC18F26K22 07.06.2015 


BP FlashForth PIC18F26K22 07.06.2015 


$ff93 constant trisb ok<$,ram> 

: init 1 trisb mclr ; \ want RB0 as output ok<$,ram> 

: do_output latb c@ 1 xor latb c! ; \ toggle RB0 ok<$,ram> 
: wait #500 ms ; ok<$,ram> 

: main init begin do_output wait again ; ok<$,ram> 


File Log Micro Help 


FlashForth Shell 



ok<$,ram> 


rJ 


Serial Port - - 

Device:/dev/ttyUSBO Speed: 38400 ParityAndBits: n,8,l Hand Shake:jxonxoff State: open 


We find ff-shell.tel a very convenient interaction environment, however, if you want 
to use a standard terminal program on Linux or MacOSX, Appendix A provides a few 
notes for doing so. 
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5 Introductory examples 

We begin with examples that demonstrate a small number of features of the MCU or of 
FlashForth. Our interest will primarily be in driving the various peripherals of the MCU 
rather than doing arithmetic or dealing with abstract data. 

5.1 Hello, World: Flash a LED on the PIC18FX6K22 

The microcontroller version of the “Hello, World” program is typically a program that 
flashes a single LED. It will work on either of PIC18F microcontrollers mentioned pre¬ 
viously and makes use of a digital input-output pin via the registers that control the 10 
port. The datasheet [2] has a very readable introduction to the 10 ports. Please read it. 


1 -flash-led 

2 marker -flash-led 

3 $ff8a constant latb 

4 $ff93 constant trisb 

5 : init 1 trisb mclr ; \ want RBO as output 

6 : do_output latb c@ 1 xor latb c! ; \ toggle RBO 

7 : wait #500 ms ; 

8 : main init begin do_output wait again ; 

9 main 


Notes on this program: 

• If the word -flash-led has been previously defined with the word marker, line 1 
resets the dictionary state and continues interpreting the hie, else the interpreter 
signals that it can’t find the word and continues interpreting the hie anyway. 

• Line 2 records the state of the dictionary and defines the word -flash-led so that 
we can reset the dictionary to its state before the code was compiled, simply by 
executing the word -flash-led. 

• Lines 3 and 4 define convenient names for the addresses of the hie registers that 
control IO-port B. Note the literal hexadecimal notation with the $ character. In 
the PIC18F family, the special function registers for interacting with the MCU 
hardware appear near the top of the 64k FlashForth memory space. 

• Line 5 is a colon definition for the word init that sets up the peripheral hardware. 
Here, we set pin RBO as output. The actual command that does the setting is 
mclr, which takes a bit-mask (00000001) and a register address ($ff93) and then 
clears the register’s bits that have been set in the mask. Note the comment starting 
with the backslash character. Although the comment text is sent to the MCU, it is 
ignored. Note, also, the spaces delimiting words. That spaces after the colon and 
around the semicolon are important. 

• Line 6 is the definition that does the work of fiddling the LED pin. We fetch the 
byte from the port B latch, toggle bit 0 and store the resulting byte back into the 
port B latch. 
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• Line 7 defines a word to pause for 500 milliseconds. Note the # character for a literal 
decimal integer. 

• Line 8 defines the “top-level” coordination word, which we have named main, fol¬ 
lowing the C-programming convention. After initializing the relevant hardware, it 
unconditionally loops, doing the output operation and waiting, each pass. 

• Line 9 invokes the main word and runs the application. Pressing the Reset button 
will trigger a hardware restart, kill the application and put the MCU back into a 
state of listening to the serial port. Invoking a warm restart by typing Control-0 
or selecting the Warm Restart menu action in f f-shell. tel may be a more conve¬ 
nient way to stop the application. Typing main, followed by Enter will restart the 
application. 

Instead of going to the bother of tinkering with the MCLI 10 Port, we could have taken 
a short-cut and used the string writing capability of Forth to write a short version that 
was closer the the operation of typical Hello World programs. 


1 : greet-me Hello World" ; 

2 greet-me 


Before going on to more examples, it is good to know about the word empty. This word 
will reset the dictionary and all of the allotted-memory pointers. Because FlashForth does 
not allow you to redefine words that are already in the dictionary, later examples that 
use the same names for their word definitions, may not compile without complaint if you 
don’t clean up after each exercise. 


5.2 Flash a LED on the PIC24FV32KA302 


1 -flash-led 

2 marker -flash-led 

3 $02c8 constant trisb 

4 $02cc constant latb 

5 1 #15 lshift constant bitl5 

6 : init bitl5 trisb mclr ; \ set pin as output 

7 : do_output latb @ bitl5 xor latb ! ; \ toggle the bit 

8 : main init begin do_output #500 ms again ; 

9 main 


Notes on this program: 

• This program for the 16-bit microcontroller is essentially the same as that for the 
8-bit MCU, with different addresses for the port-control registers, of course. In 
the PIC24/dsPIC30/dsPIC33 version of FlashForth, the special function registers 
appear in the lowest 2k bytes of memory. 
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• On line 5, we compute the bit pattern for selecting the MCU pin rather than writing 
it explicitly. We start with a 1 in the least-significant bit of the 16-bit word and 
then shift it left 15 places, to produce the binary value °/„1000000000000000 

• On line 7, we use 16-bit fetch @ and store ! operations because the hardware special 
function registers on this microcontroller are 16 bits wide. 


5.3 Flash a LED on the ATmega328P 


1 -flash-led-avr 

2 marker -flash-led-avr 

3 \ PB5 is Arduino digital pin 13. 

4 \ There is a LED attached to this pin on the Freetronics Eleven. 

5 

6 $0024 constant ddrb 

7 $0025 constant portb 

8 1 #5 lshift constant bit5 

9 

10 : init bit5 ddrb mset ; \ set pin as output 

11 : do_output portb c@ bit5 xor portb c! ; \ toggle the bit 

12 : main init begin do_output #500 ms again ; 

13 

14 main 


Notes on this program: 

• Again, except for the specific registers and bits, this program is the same as for the 
other MCUs. As for other high-level languages, we no longer have to think about 
the specific machine architecture (usually). 

• Because we are using load and store instructions, the special function registers start 
at address $20. 
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5.4 Set the cycle duration with a variable (PIC18FX6K22) 

We enhance the initial demonstration by making the waiting period setable. Because of 
the interactive FlashForth environment, the extra programming effort required is tiny. 
The appearance of the code, however, looks a bit different because we have laid out the 
colon definitions in a different style and have included more comments. 


1 

-flash-led-var 


2 

marker -flash-led-var 


3 

\ Flash a LED attached to 

pin RBO. 

4 



5 

$ff8a constant latb 


6 

$ff93 constant trisb 


7 

variable ms.count \ use this for setting wait 

8 



9 

: init ( -- ) 


10 

1 trisb mclr \ want RBO 

as output 

11 

; 


12 



13 

: do_output ( -- ) 


14 

latb c@ 1 xor latb c! \ 

toggle RBO 

15 

; 


16 



17 

: wait ( -- ) 


18 

ms.count @ ms 


19 

; 


20 



21 

: main ( n -- ) 


22 

ms.count ! \ store for 

later use in wait 

23 

init 


24 

begin 


25 

do_output 


26 

wait 


27 

again 


28 

; 


29 



30 

#500 main \ exercise the 

application 


Notes on this program: 

• If the file has been sent earlier defining the application’s words, line 1 resets the 
state of the dictionary to forget those previous definitions. This makes it fairly 
convenient to have the source code open in an editing window (say, using eraacs) 
and to simply reprogram the MCU by resending the file (with the Send-File menu 
item in ff-shell.tcl). 

• Line 7 defines a 16-bit variable ms_count. 

• Line 30 leaves the wait period on the stack before invoking the main word. 

• On each pass through the wait word, the 16-bit value is fetched from ms_count and 
is used to determine the duration of the pause. 
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5.5 Hello, World: Morse code 

Staying with the minimal hardware of just a single LED attached to pin RBO on the 
PIC18F26K22 or PIC18F46K22, we can make a proper “Hello World” application. The 
following program makes use of Forth’s colon definitions so that we can spell the message 
directly in source code and have the MCU communicate that message in Morse code. 


1 -hello-world 

2 marker -hello-world 

3 \ Flash a LED attached to pin RBO, sending a message in Morse-code. 

4 

5 $ff8a constant latb 

6 $ff93 constant trisb 

7 variable ms.count \ determines the timing. 

8 

9 : init ( -- ) 

10 1 trisb mclr \ want RBO as output 

11 1 latb mclr \ initial state is off 

12 ; 

13 

14 : led_on 1 latb mset ; 

15 : led_off 1 latb mclr ; 

16 : gap ms.count 0 ms ; \ pause period 

17 : gap2 gap gap ; 

18 : dit led_on gap led_off gap2 ; 

19 : dah led_on gap2 led_off gap2 ; 

20 

21 \ Have looked up the ARRL CW list for the following letters. 

22 : H dit dit dit dit ; 

23 : e dit ; 

24 : 1 dit dit ; 

25 : o dah dah dah ; 

26 : W dit dah dah ; 

27 : r dit dah dit ; 

28 : d dah dit dit ; 

29 

30 : greet ( -- ) 

31 Hello gap World gap2 

32 ; 

33 

34 : main ( n -- ) 

35 ms.count ! \ store for later use in gap 

36 init 

37 begin 

38 greet 

39 again 

40 ; 

41 

42 #100 main \ exercise the application 
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21 
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6 Read and report an analog voltage 

6.1 PIC18FX6K22 



Use of the analog-to-digital converter 


matter of, first, reading Section 17 of 


the PIC18F2X/4XK22 datasheet [2], setting the relevant configuration/control registers 
and then giving it a poke when we want a measurement. Again, the interactive nature of 
FlashForth makes the reporting of the measured data almost trivial. 


-read -adc 
marker -read-adc 

\ Read and report the analog value on RA0/AN0. 

\ Registers of interest on the PIC18F26K22 

$ffc4 constant adresh 

$ffc3 constant adresl 

$ffc2 constant adconO 

$ffcl constant adconl 

$ffc0 constant adcon2 

$ff92 constant trisa 

$ff38 constant ansela 

: init ( -- ) 

1 trisa mset \ want RAO as input 
1 ansela mset 

7,00000000 adconl c! \ ADC references Vdd , Vss 

7,10101111 adcon2 c! \ r ight - j ust if ied , 12-TAD acq-time , FRC 

7,00000001 adconO c! \ Power on ADC, looking at AN0 

: adc@ ( -- u ) 

7,10 adconO mset \ Start conversion 

begin 1 10 adconO mtst 0= until \ Wait until DONE 

adresl 0 


: wait ( -- ) 

#500 ms 

: main ( — ) 
init 
begin 

adc@ u. 
wait 

key? until 

\ Exercise the application, writing digitized values periodically 

\ until any key is pressed. 

decimal 

main 


Notes on this program: 

• Although not much needs to be done to set up the ADC, you really should read the 
ADC section of the datasheet to get the full details of this configuration. 

• Lines 17 to 19 uses binary literals (with the °/„ character) to show the configuration 
bits explicitly. 
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• Line 24 conditionally repeats testing of the DONE bit for the ADC. 

• Line 25 fetches the full 10-bit result and leaves it on the stack for use after the adc@ 
word has finished. Because of the selected configuration of the ADC peripheral, the 
value will be right-justified in the 16-bit cell. 

• Line 35 invokes the adc@ word and prints the numeric result. 

• Line 37 checks if a character has come in from the serial terminal. If so, the loop is 
terminated and the main function returns control to the FlashForth interpreter. 


6.2 PIC24FV32KA30X 

The analog-to-digital converter on the PIC24-series microcontrollers is a little more com¬ 
plex than that on the PIC18 series. There are more features to select and so there are 
more registers and bits to set, however, the essential set-up tasks are similar. The follow¬ 
ing script sets up some word definitions that were developed with a view to using them in 
a larger program. The particular words are more verbose but also carry more information. 


1 -read-adc 

2 marker -read-adc 

3 \ Read and report the analog values on ANO through AN3 . 

4 

5 \ Registers of interest on the PIC24FV32KA30x 

6 $0084 constant ifsO 

7 

8 $02c0 constant trisa 

9 $02c2 constant porta 

10 $02c4 constant lata 

11 $02c6 constant odea 

12 

13 $02c8 constant trisb 

14 $02ca constant portb 

15 $02cc constant latb 

16 $02ce constant odeb 

17 

18 $0300 constant adclbufO 

19 $0340 constant adlconl 

20 $0342 constant adlcon2 

21 $0344 constant adlcon3 

22 $0348 constant adlchs 

23 

24 $04e0 constant ansa 

25 $04e2 constant ansb 

26 

27 $0770 constant pmdl 

28 

29 \ bit masks 

30 $0001 constant mADCIMD \ pmdl 

31 $0001 constant mDONE \ adlconl 

32 $0002 constant mSAMP 

33 $8000 constant mADON 

34 $2000 constant mADHF 

35 

36 

37 : adc.init ( -- ) 

38 $0003 trisa mset \ want RAO, RA1 as input 

39 $0003 ansa mset 

40 $0003 trisb mset 

41 $0003 ansb mset 
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42 mADCIMD pmdl mclr \ ensure module enabled 

43 $0470 adlconl ! \ 12-bit, auto-convert 

44 $0000 adlcon2 ! \ ADC references Vdd , Vss 

45 $9f00 adlcon3 ! \ ADRC, 31-TAD acq-time 

46 $0000 adlchs ! \ neg input is Vss , pos input AN0 

47 mADON adlconl mset \ Power on ADC 

48 mADHF ifsO mclr 

49 ; 

50 

51 : adc . close ( -- ) 

52 mADON adlconl mclr 

53 mADHF ifsO mclr 

54 ; 

55 

56 : adc.select ( u -- ) \ select positive input 

57 $0003 and adlchs ! \ limit selection to AN0 through AN3 

58 ; 

59 

60 : adc@ ( -- u ) 

61 mDONE adlconl mclr 

62 mSAMP adlconl mset \ Start sampling 

63 begin mDONE adlconl mtst until \ Wait until done. 

64 adclbufO @ 

65 ; 

66 

67 : adc@ .filter ( -- u ) 

68 0 \ start of sum 

69 8 for adc@ + next 

70 8 / 

71 ; 

72 

73 : wait ( -- ) 

74 #500 ms 

75 ; 

76 

77 : adc .test ( -- ) 

78 adc . init 

79 begin 

80 0 adc.select adc@ 

81 1 adc.select adc@ 

82 cr 

83 wait 

84 key? until 

85 adc.close 

86 ; 

87 

88 \ Exercise the application, writing digitized values periodically 

89 \ until any key is pressed. 

90 \ decimal 

91 \ adc .test 


.filter u. 
.filter u. 


Notes on this program: 

• This script was part of a larger application for the monitoring of 2 pressure trans¬ 
ducers, hence the setting up of just RAO and RA1 at the start of adc. init at lines 
38-41. 

• To save power the peripheral modules of a PIC24 are, by default, disabled. You 
need to clear a module’s disable bit (line 42) to do anything with it, even setting 
configuration registers. The (separate) power-on bit still needs to be set to start up 
the converter. 
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6.3 ATmega328P 

Although the analog-to-digital converter on the ATmega328P is different in detail, it has 
essentially the same functionality that can be abstracted. To control the ADC module, 
we can set up the same words (adc.init, adc. close, adc. select and adc@) as for the 
PIC24FV32KA302. 


1 -read-adc 

2 marker -read-adc 

3 \ Read and report analog voltages 

4 

5 \ Registers of interest on the ATmega328P 

6 $78 constant add 

7 $79 constant adch 

8 $7a constant adcsra 

9 $7b constant adcsrb 

10 $7c constant admux 

11 $7e constant didrO 

12 

13 \ Bit masks 

14 # / 0 10000000 constant mADEN 

15 # / 0 01000000 constant mADSC 

16 y o 00010000 constant mADIF 

17 

18 : adc.clear.iflag ( -- ) 

19 mADIF adcsra mset \ clear by writing 1 

20 ; 

21 

22 : adc . init ( -- ) 

23 $3f didrO c! \ Disable digital inputs 5 through 0 

24 $40 admux c! \ AVcc as ref, right-adjust result, channel 0 

25 $06 adcsra c! \ single conversion mode, prescaler 64 

26 mADEN adcsra mset \ enable ADC 

27 adc . clear . if lag 

28 ; 

29 

30 : adc.close ( -- ) 

31 mADEN adcsra mclr 

32 adc . clear . if lag 

33 ; 

34 

35 : adc.wait ( -- ) 

36 begin mADSC adcsra mtst 0= until 

37 ; 

38 

39 : adc.select ( u -- ) 

40 adc . wait 

41 $0f and \ channel selected by lower nibble 

42 admux c@ $f0 and \ fetch upper nibble 

43 or admux c ! 

44 ; 

45 

46 : adc@ ( -- u ) 

47 adc . wait 

48 mADSC adcsra mset 

49 adc.wait 

50 add c@ adch c@ #8 lshift or 

51 adc . clear . if lag 

52 ; 

53 

54 : adc .test ( -- 

55 adc . init 

56 begin 

57 0 adc.select 

58 1 adc . select 

59 cr 

60 #500 ms 

61 key? until 


) \ Exercise the analog converter 


adc@ ." adcO " u. 
adc@ ." adc1 " u. 
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62 adc . close 

63 ; 

64 

65 \ Now, start up the application... 

66 \ decimal 

67 \ adc .test 


Notes on this program: 

• Although there are 6 analog pins available, the test word only exercises channels 0 
and 1. 

• The input channel selection is controlled by the lower bits in the admux register. 
Other than the 6 external analog input pins, you can select: 

— the temperature sensor with bit pattern %1000, 

— the internal band-gap reference with 7 0 1110, and 

— and the zero-volt rail (GND) with %1111. 
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7 Counting button presses 

Example of sensing a button press, with debounce in software. 


1 \ Use a push-button on RBO to get user input. 

2 \ This button is labelled S3 on the PICDEM2+ board. 

3 -pb-derao 

4 marker -pb-demo 

5 

6 $ff81 constant portb 

7 $ff8a constant latb 

8 $ff93 constant trisb 

9 

10 variable count 

11 

12 : init ( -- ) 

13 °/ 0 01 trisb mset \ RBO as input 

14 7,10 trisb mclr \ RBI as output 

15 7,10 latb mclr 

16 ; 

17 : RBltoggle ( -- ) 

18 latb c@ 7.10 xor latb c ! 

19 ; 

20 : RB0@ ( -- c ) 

21 portb c@ 7.01 and 

22 ; 

23 : button? ( -- f ) 

24 \ Check for button press, with software debounce. 

25 \ With the pull-up in place, a button press will give 0. 

26 RB0@ if 

27 0 

28 else 

29 #10 ms 

30 RB0@ if 0 else -1 then 

31 then 

32 ; 

33 

34 : main ( -- ) 

35 0 count ! 

36 init 

37 begin 

38 button? if 

39 RBltoggle 

40 count 0 1+ count ! 

41 count @ . 

42 #200 ms \ allow time to release button 

43 then 

44 cwd 

45 key? until 

46 ; 

47 

48 main \ exercise the application 


Notes on this program: 

• The main word clears the count variable, calls init to set up the hardware and 
then loops, polling RBO and incrementing value of the count variable only when the 
button gets pressed. 

• If the pause after acknowledging the button press (line 42) is too long, we may lose 
later button press events. This depends on how frantically we press S3. 
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• Line 44 resets the watch-dog tinier on each pass of the main loop. If we don’t press 
the RBO button for a long time, the main loop would not otherwise pause and clear 
the watch-dog timer. The watch-dog timer is cleared inside the ms word, however, 
if the timer expires before being cleared, the microcontroller would be reset and the 
FlashForth interpreter would restart. 
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8 Counting button presses via interrupts 

Instead of polling the RBO pin attached to the push button, as in the previous example, 
let’s set up the hardware interrupt mechanism to invoke the increment action for us. 


1 \ Use a push-button on RBO to get user input, via an interrupt. 

2 \ This button is labelled S3 on the PICDEM2+ board. 

3 \ Don’t have J6 connected because the LED on RBO loads the pull-up. 

4 

5 -pb-interrupt 

6 marker -pb-interrupt 

7 

8 $ff93 constant trisb 

9 $fff2 constant intcon 

10 $fffl constant intcon2 

11 

12 variable count 

13 variable last-count 

14 

15 : intO-irq 

16 [i 

17 °/«10 intcon mtst \ INTOIF 

18 if 

19 count @ 1+ count ! 

20 7o 10 intcon melr 

21 then 

22 i] 

23 ; i 

24 

25 : init ( -- ) 

26 °/ 0 01 trisb mset \ RBO as input, a button press will give 0. 

27 7,01000000 intcon2 mclr \ interrupt on falling edge 

28 [’] intO-irq 0 int! \ install service word 

29 7,10 intcon mclr \ INTOIF cleared 

30 7,10000 intcon mset \ INTO interrupt enable 

31 ; 

32 

33 : main ( -- ) 

34 0 count ! 

35 init 

36 begin 

37 count 0 last-count <9 - \ change? 

38 if 

39 count @ dup last-count ! . 

40 then 

41 cwd 

42 key? until 

43 ; 

44 

45 main \ exercise the application 


Notes on this program: 

• Again, we use the variable named count as the variable to be incremented on press¬ 
ing the button that pulls RBO low. The actual increment is done on line 19, inside 
the interrupt service word intO-irq. The second variable, last-count, is used on 
line 36 in the main word, to detect when the count variable changes. 

• The init word sets up the bits to enable the INTO external interrupt to fire on a 
falling edge at RBO. 
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• On line 28 in the init word, the execution token for our interrupt service word 
is stored as the high-priority interrupt vector. Because FlashForth supports only 
high-priority interrupts, the 0 is a dummy value but is still expected by the int! 
word. 

• Inside the interrupt-service word, we need to test the INTO IF interrupt flag to see if 
it is our interrupt to handle and, if it is, do the appropriate work (of incrementing 
the count variable) and clearing the interrupt flag. If you enable several interrupt 
sources, you need to provide a test and action for each. 

• The main word clears the count variable, calls init to set up the interrupt mecha¬ 
nism and then loops, emitting the value of the count variable only when it changes. 
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9 Scanning a 4x3 matrix keypad 

We connect a 4x3 matrix keypad to PORTB, using RBO, RBI and RB2 to drive the 
columns while sensing the rows with RB4 through RB7. The schematic figure below 
shows the arrangement of keys and pins. 

pin 2, RB7 
pin 7, RB6 
pin 6, RB5 
pin 4, RB4 

pin 3 1 5 

RBO RBI RB2 

To minimize hardware, we have used the weak pull-ups on PORTB. Pressing a key while 
its column wire is held high does nothing, however, pressing a key on a column that is 
held low will result in its row being pulled low. 



l -keypad 


2 

marker 

-keypad 


3 

\ Display key 

presses 

4 

\ on P 

IC18F26K22-I/SP 

5 

6 

$f f 81 

constant 

portb 

7 

$f f 8a 

constant 

latb 

8 

$f f 93 

constant 

trisb 

9 

$f f 39 

constant 

anselb 

10 

$f f 61 

constant 

wpub 

11 

$f f f 1 

constant 

int con2 


from a 4x3 (telephone-1ike) 


12 

13 

14 

15 

16 

17 

18 

19 

20 
21 
22 

23 

24 

25 

26 
27 


init ( — 
0 latb c ! 
7,00000000 
7,11110000 
7.11H0000 
7.10000000 


flash 


) 

anselb c ! 
trisb c! 
wpub c ! 
intcon2 mclr 


\ set as all digital 1/0 
\ RB7-4 as input, RB3-0 
\ pull-ups on RB7-4 
\ turn on pull-ups 


create 

key _ 

chars 





char 

1 c , 

char 

2 c, 

char 

3 

c 

char 

4 c , 

char 

5 c , 

char 

6 

c 

char 

7 c , 

char 

8 c , 

char 

9 

c 

char 

* c , 

char 

0 c, 

char 

# 

c 

create 

key_ 

scan. 

bytes 





28 

$7e 

c , 

$7d 

C , 

$7b 

c 

29 

$be 

c , 

$bd 

c , 

$bb 

c 

30 

$de 

c , 

$dd 

c , 

$db 

c 

31 

$ee 

c , 

$ed 

c , 

$eb 

c 


32 

33 

34 

35 

36 

37 

38 

39 

40 

41 

42 

43 

44 


scan_keys ( -- c ) 

\ Return ASCII code 
#12 for 

key_scan_bytes r@ + c@ 
dup 

latb c! 
portb c@ 

= if 

\ key must be pressed 
key.chars r@ + c@ 
rdrop 


of key that is pressed 


to get a match 


keypad 


pins 

as output 
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45 exit 

46 then 

47 next 

48 0 \ no key was pressed 

49 ; 

50 

51 : keypad® ( -- c ) 

52 \ Read keypad with simple debounce. 

53 \ ASCII code is left on stack. 

54 \ Zero is returned for no key pressed or inconsistent scans. 

55 scan_keys dup 

56 #20 ms 

57 scan_keys 

58 = if exit else drop then 

59 0 \ inconsistent scan results 

60 ; 

61 

62 : main ( -- ) 

63 init 

64 begin 

65 keypad® 

66 dup 

67 0= if 

68 drop \ no key pressed 

69 else 

70 emit 

71 #300 ms \ don’t repeat key too quickly 

72 then 

73 key? until 

74 ; 


Notes on this program: 

• In lines 21-31, we make use of character arrays to store (into the program memory) 
the the ASCII code and the scan code for each key. The scan code is made up of 
the 3-bit column pattern to be applied to RB2-RB0 and the resulting 4-bit row- 
sense pattern (RB7-RB4) expected for the particular key if it is pressed. RB3 is 
maintained high (and is of no consequence) for this 3-column keypad, however, it 
would be used for a 4x4 keypad. 

• Lines 36 and 47 make use of the for-next control construct to work through the set 
of 12 scan codes 

• We should go further by making use a state-machine and also keeping track of the 
last key pressed. 
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10 Communicating with SPI devices 


The photograph below shows the Eleven AVR board driving a matrix display. This 
particular display board has an 8x8 LED matrix being controlled by a MAX7219 8-digit 
LED display driver [ ]. 



The MAX7219 has a serial data interface that can be driven by the SPI module within 
each of the microcontrollers. The timing diagram, taken directly from the datasheet [9], 
is shown below, along with the expect format for each 16-bit command. A command can 
be sent to the MAX7219 chip by taking the chip-select line low, sending two bytes via 
the SPI module and then taking the chip-select line high. A set of words for doing this 
2-byte transfer and building the higher-level commands on top of that transfer is given in 
Section 10.4. 



Table 1. Serial-Data Format (16 Bits) 


D15 

D14 

D13 

D12 

Dll 

DIO 

D9 

D8 

D7 

D6 

D5 

D4 

D3 

D2 

D1 

DO 

X 

X 

X 

X 

ADDRESS 

MSB DATA LSB 


The following sections define the words for using SPI peripherals for each of the microcon¬ 
trollers in master mode. The SPI module is initialized for mode 0 operation, with clock 
signal idling low, and data lines changing as the clock signal transitions from active to 
idle. This suits the MAX7219, which samples the data as the clock signal transitions from 
idle to active. These words provide abstract the hardware registers and bits to provide a 
common vocabulary for the interaction with SPI slave devices. 


























































10 COMMUNICATING WITH SPI DEVICES 


37 


10.1 PIC18FX6K22 


1 \ spi2-base-k22.txt 

2 \ Words to drive the SPI2 module on the PIC18F26K22 

3 \ PJ 31-Jan-2016 

4 -spi2-base 

5 marker -spi2-base 

6 


7 

\ Registers of 

interest for MSSP2 

8 

$f f 39 

constant 

anselb 

9 

$f f 61 

constant 

wpub 

10 

$f f 69 

constant 

s sp2con3 

11 

$f f 6c 

constant 

s sp2conl 

12 

$f f 6d 

constant 

ssp2stat 

13 

$f f 6e 

constant 

ssp2add 

14 

$f f 6f 

constant 

ssp2buf 

15 

$f f 81 

constant 

portb 

16 

$f f 8a 

constant 

latb 

17 

$f f 93 

constant 

trisb 

18 

$f f a4 

constant 

pir3 

19 

$f ff 1 

constant 

int con2 

20 




21 

\ bit 

masks 


22 

7,0001 

constant 

mSS2 ( RB0 ) 

23 

70010 

constant 

mSCK2 ( RBI ) 

24 

70100 

constant 

mSDI2 ( RB2 ) 

25 

71000 

constant 

mSD02 ( RB3 ) 


26 $80 constant mRBPU 

27 $80 constant mSSP2IF 

28 $20 constant mSSP2EN 

29 

30 \ !SS2 is on RB0 

31 : spi.select ( -- ) mSS2 latb mclr ; 

32 : spi.deselect ( -- ) mSS2 latb mset ; 

33 

34 : spi.init ( -- ) \ set up SPI2 as master 

35 $0f anselb mclr \ enable digital for RB3 through RB0 

36 mSCK2 trisb mclr \ SCK as output 

37 mSCK2 latb mclr \ clock idles low 

38 mSD02 trisb mclr \ M0SI as output 

39 mSDI2 trisb mset \ MIS0 as input 

40 $04 wpub c! \ activate pull-up on MIS0 (RB2) only 

41 mRBPU intcon2 mclr \ enable pull-ups 

42 mSS2 trisb mclr \ SS2 as output 

43 mSS2 latb mset \ deselect 

44 °/o01000000 ssp2stat c! \ SMP=0 CKE = 1 

45 y o 00100010 ssp2conl c! \ enable, CKP=0, Fosc/64 

46 mSSP2IF pir3 mclr 

47 ssp2buf c@ drop \ will clear BF 

48 ; 

49 : spi.close ( -- ) 

50 mSSP2EN ssp2conl mclr 

51 mSSP2IF pir3 mclr 

52 ; 

53 : spi . wait ( -- ) 

54 begin mSSP2IF pir3 mtst until 

55 mSSP2IF pir3 mclr 

56 ; 

57 : spi.cexch ( cl -- c2 ) ssp2buf c! spi.wait ssp2buf c@ ; 

58 : spi.csend ( cl -- ) spi.cexch drop ; 

59 

60 : spi.test ( -- ) 

61 spi.init 

62 spi . select 

63 $lc spi.csend \ an arbitrary byte 

64 spi.deselect 

65 spi . close 

66 ; 



1 

2 

3 

4 

5 

6 

7 

8 

9 

10 

11 

12 

13 

14 

15 

16 

17 

18 

19 

20 

21 

22 

23 

24 

25 

26 

27 

28 

29 

30 

31 

32 

33 

34 

35 

36 

37 

38 

39 

40 

41 


10 COMMUNICATING WITH SPI DEVICES 


38 


Notes on this program: 

• For the PIC18F26K22, we choose to use the second SPI module because we have 
the pins associated with the first module assigned to the I 2 C communications, as 
discussed in Section 11. 

• Lines 40 and 41 activate the weak pull-up for the MISO pin. Some slave devices, 
such as the MAX7219, do not have a data-out pin to talk back to the master. 

• The key word spi . cexch starts the exchange of a byte by writing it to the SPI data 
buffer. On completion of the transfer, detected by the interrupt flag going high, the 
incoming byte is fetched from the same buffer. If there is no data line connected to 
the MISO pin, a byte of all Is will be returned. If you know that is the expected, 
it may be convenient to use the spi. csend which does the same exchange but then 
drops the incoming byte. 

10.2 PIC24FV32KA30X 


\ spil-base-pic24fv32ka302.txt 

\ Words to drive the SPI1 module on the PIC24FV32KA302 
\ PJ 01-Feb-2016 
-spi1-base 
marker -spil-base 


\ Registers of 
$0070 constant 
$0084 constant 
$02c8 constant 
$02ca constant 
$02cc constant 
$02ce constant 
$0240 constant 
$0242 constant 
$0244 constant 
$0248 constant 
$04e2 constant 
$0770 constant 


interest for SPI1 

cnpu2 \ CN16PUE is bit 0 

if sO \ SPI 1 IF is bit 10 

trisb 

portb 

latb 

odcb 

spilstat 
spi1coni 
spi1con2 
spilbuf 
ansb 

pmdl \ SPI1MD is bit 3 


\ bit masks 
$8000 constant 
$0800 constant 
$0400 constant 
$2000 constant 
$0400 constant 
$8000 constant 
$0040 constant 


mSSl ( RB15 ) 
mSCKl ( RB11 ) 
mSDIl ( RB10 ) 
mSDOl ( RBI3 ) 
mSPIUF 
mSPIEN 
mSPIROV 


\ ! SSI is on RB 15 

: spi . select ( -- ) mSSl latb mclr ; 

: spi.deselect ( -- ) mSSl latb mset ; 

: spi . init ( -- ) \ set up SPI1 as master 

$ac ansb mclr \ enable digital for RB15 ,13,11 ,10 

mSCKl trisb mclr \ SCK as output 

mSCKl latb mclr \ clock idles low 

mSDOl trisb mclr \ M0SI as output 

mSDIl trisb mset \ MISO as input 

$0001 cnpu2 ! \ activate pull-up on MISO (SDI1/CN16/RB10) only 

mSSl trisb mclr \ SSI as output 




42 

43 

44 

45 

46 

47 

48 

49 

50 

51 

52 

53 

54 

55 

56 

57 

58 

59 

60 

61 

62 

63 

64 

65 

66 

67 

68 

1 

2 

3 

4 

5 

6 

7 

8 

9 

10 

11 

12 

13 

14 

15 

16 

17 

18 

19 

20 
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mSSl latb mset \ deselect 

$0004 pmdl mclr \ allow the module to be used 
$013d spilconl ! \ M0DE16=0, SMP=0 CKE=1, CKP=0, MSTEN=1 
\ sec-prescale 1:1, pri-prescale 16:1 
$0000 spilcon2 ! \ legacy mode 

mSPIROV spilstat mclr 

mSPIEN spilstat mset \ enable module 
mSPIUF ifsO mclr 

: spi.close ( -- ) 

mSPIEN spilstat mclr 
mSPIUF ifsO mclr 

: spi.wait ( -- ) 

begin mSPIUF ifsO mtst until 
mSPIUF ifsO mclr 

: spi . cexch ( cl -- c2 ) spilbuf c! spi . wait spilbuf c@ ; 

: spi . csend ( cl -- ) spi . cexch drop ; 

: spi.test ( -- ) 
spi.init 
spi.select 

$lc spi . csend \ an arbitrary byte 
spi.deselect 
spi.close 


Notes on this program: 

• On this microcontroller, we choose to use the first SPI module, again because it 
results in a convenient set of pins. Section 11 uses the I 2 C pins on RB5 and RB6 

• On lines 43 through 46, the SPI1 module is configured to behave much like the 8-bit 
SPI module on the PIC18F26K22. If we didn’t care about making a common set 
of words for the three example processors in this tutorial guide, we would probably 
make use of the advanced features on this 16-bit microcontroller. These features 
include 16-bit transfer and enhanced buffering. 

10.3 ATmega328P 


\ spi-base-avr.txt 

\ Words to drive the SPI module on the ATmega328P 
\ PJ 31-Jan-2016 
-spi-base 
marker -spi-base 

\ Registers of interest 
$24 constant ddrb 
$25 constant portb 
$4c constant spcr 
$4d constant spsr 
$4e constant spdr 

\ bit masks 

# /«000100 constant mSS ( PB2 ) 

°/«001000 constant mMOSI ( PB3 ) 

°/«010000 constant mMISO ( PB4 ) 

# /o 100000 constant mSCK ( PB5 ) 

$80 constant mSPIF 
$40 constant mWCOL 





21 

22 

23 

24 

25 

26 

27 

28 

29 

30 

31 

32 

33 

34 

35 

36 

37 

38 

39 

40 

41 

42 

43 

44 

45 

46 

47 

48 

49 

50 

51 
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\ ! SS 

is on PB2 






: spi . 

select ( - 

- ) 

mSS portb mclr ; 




: spi . 

deselect ( 

-- 

) mSS portb mset 

• 



: spi . 

init ( — 

) 





mSCK 

ddrb mset 

\ 

SCK as output 




mSCK 

portb mcl 

r \ 

clock idles low 




mMOS 

I ddrb mset \ 

MOSI as output 




mMISO ddrb mcl 

r \ 

MISO as input 




mMISO portb ms 

et 

\ activate pull-up 

on MI 

SO 


mSS 

ddrb mset 

\ SS as output 




mSS 

portb mset 

\ 

deselect 




$51 

spcr c ! \ 

enable as master with 

cpola 

rity 

0 

$00 

spsr c ! \ 

SPI 

2X = 0 for fosc/16 




spsr 

c@ drop s 

pdr 

c@ drop \ will cl 

ear SP 

IF 


: spi . 

close ( -- 

) 





$00 

spcr c ! 






: spi . 

wait ( 

) begin mSPIF spsr mt 

st unt 

il ; 


: spi . 

o a x c :i ( cl 

-- 

c2 ) spdr c! spi . 

wait s 

pdr 

c@ 

: spi . 

csend ( cl 

— 

) spi.cexch drop 




: spi . 

test ( -- 

) 






spi.init 
spi.select 

$lc spi . csend \ an arbitrary byte 
spi.deselect 
spi.close 


cphase 0, 


f osc/16 


Here is a screenshot showing the record of 
mega328P as it sends the single byte $0c$, 
SPI clock period is 1 microsecond. 


the SPI communication pins on the 
as specified in the spi-test word. 


AT- 

The 


Q 


File Log Micro Help 

mMOSI ddrb mset \ MOSI as output 

mMISO ddrb mclr \ MISO as input 

mMISO portb mset \ activate pull-up on MISO 

mSS ddrb mset \ SS as output 

mSS portb mset \ deselect 

$51 spcr c! \ enable as master with cpolarity 0, cphase 0, fosc/1 
$00 spsr c! \ SPI2X=0 for fosc/16 
spsr c® drop spdr c® drop \ will clear SPIF 
; ok<$,ram> 

: spi.close ( -- ) 

$00 spcr c! 
ok<$,ram> 

spi.wait ( -- ) begin mSPIF spsr mtst until ; ok<$,ram> 
spi.cexch ( cl - - c2 ) spdr c! spi.wait spdr c@ ; ok<$,ram> 
spi.csend ( cl -- ) spi.cexch drop ; ok<$,ram> 
ok<$,ram> 

: spi.test spi.init spi.select $lc spi.csend spi.deselect spi.close 
k<$,ram> 

Ispi.test ok<$,ram> 

I r Serial Port- 


File Edit Options Buffers Tools Help 

d o B * b=s 


ir* Undo 


y. o e q. 


: spi.init ( -- ) 
mSCK ddrb mset \ SCK as output 
mSCK portb mclr \ clock idles low 
mMOSI ddrb mset \ MOSI as output 
mMISO ddrb mclr \ MISO as input 
mMISO portb mset \ activate pull-up on MISO 
mSS ddrb mset \ SS as output 
mSS portb mset \ deselect 

S51 spcr c! \ enable as master with cpolarity 0, cphase 0, fosc/16 

S00 spsr cl \ SPI2X-0 for fosc/16 

spsr c@ drop spdr c@ drop \ will clear SPIF 

: spi.close ( -- ) 

SOB spcr c! 

: spi.wait ( -- ) begin mSPIF spsr mtst until ; 

: spi.cexch ( cl -- c2 ) spdr cl spi.wait spdr c@ ; 

: spi.csend ( cl -- ) spi.cexch drop ; 

: spi.test spi.init spi.select Sl@ spi.csend spi.deselect spi.close ; 


| Device:/dev/ttyACMO 


ParityAndBits:|n.8.1 Hand Shake:[xonxoff State:[open 


Wrote /home/peterj/avr-work/ff5-on-arduino-examples/spi-base-avr.txt 





* > 
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10.4 Words to drive a matrix display 

Given the base words defined in the previous sections, any of the boards may drive the 
matrix display with the following words. The interesting commands are defined by line 
20 and the disp-test-X words are three examples of doing something with the display. 


1 \ led-matrix-display.txt 

2 \ Drive a MAX7219 display chip with 8x8 LED matrix 

3 -disp-max7219 

4 marker -disp-max7219 

5 

6 : max7219.send ( cl c2 -- ) 

7 swap spi.select spi.csend spi.csend spi.deselect 

8 ; 

9 

10 : disp.normal ( -- ) $0c $01 max7219.send ; 

11 : disp.shutdown ( -- ) $0c $00 max7219.send ; 

12 

13 : disp.test.on ( -- ) $0f $01 max7219 . send ; 

14 : disp.test.off ( -- ) $0f $00 max7219.send ; 

15 

16 : disp.no.op ( -- ) $00 $00 max7219.send ; 

17 : disp.intensity ( c -- ) $0a swap max7219.send ; 

18 : disp.decode ( c -- ) $09 swap max7219.send ; 

19 : disp . scan. limit ( c -- ) $0b swap max7219 . send ; 

20 : disp.set.digit ( cbits cdigit -- ) swap max7219.send ; 

21 

22 : disp-test-1 ( -- ) \ all LEDs on full, 232mA needed 

23 spi . init 

24 disp . test . on 

25 begin key? until 

26 disp . test . of f 

27 spi.close 

28 ; 

29 : disp-test-2 ( -- ) \ left 4 LEDs on first row, 42mA needed 

30 spi.init 

31 disp.normal 

32 $03 disp.intensity 

33 $00 disp.scan.limit 

34 $f0 $01 disp.set.digit 

35 begin key? until 

36 disp.shutdown 

37 spi.close 

38 ; 

39 : disp-test-3 ( -- ) \ draw face, 18mA needed 

40 spi.init 

41 disp.normal 

42 $01 disp.intensity 

43 $07 disp.scan.limit 

44 '/oOOOOOOOO $01 disp . set . digit 

45 7o01100110 $02 di sp . set . digit 

46 °/ 0 00000000 $03 di sp . set . digit 

47 7o00011000 $04 di sp . set . digit 

48 7 0 00011000 $05 di sp . set . digit 

49 °/ 0 10000001 $06 di sp . set . digit 

50 # /o01000010 $07 disp . set . digit 

51 # /o00111100 $08 di sp . set . digit 

52 begin key? until 

53 disp.shutdown 

54 spi . close 

55 ; 
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11 Communicating with I2C devices 

Here are some words for using I 2 C (or Two-wire) peripherals for each of the microcon¬ 
trollers in master mode. These words provide abstract the hardware registers and bits to 
provide a common vocabulary for the interaction with 1 2 C slave devices. 

11.1 PIC18FX6K22 

1 \ i2c-base-k22.txt 

2 \ Low-level words for I2C master on PIC18F26K22 

3 \ 

4 \ Modelled on the original i2c-base.txt for PIC18, 

5 \ i2c-twi.frt from amforth and 

6 \ the datasheet for Microchip PIC18F26K22. 

7 \ Peter J. 2014-11-08 

8 

9 -i2c-base-k22 

10 marker -i2c-base-k22 

11 hex ram 

12 

13 \ Registers related to I2C operation of MSSP1 

14 $ff3a constant anselc 

15 $ff82 constant portc 

16 $ff8b constant late 

17 $ff94 constant trisc 

18 $ff9e constant pirl 

19 $ffc5 constant ssplcon2 

20 $ffc6 constant ssplconl 

21 $ffc7 constant ssplstat 

22 $ffc8 constant sspladd 

23 $ffc9 constant ssplbuf 

24 $ffca constant ssplmsk 

25 $ffcb constant ssplcon3 

26 

27 \ Masks for bits 

28 700000001 constant mSEN \ in ssplcon2 

29 # / 0 00000010 constant mRSEN 

30 # / 0 00000100 constant mPEN 

31 700001000 constant mRCEN 

32 700010000 constant mACKEN 

33 700100000 constant mACKDT 

34 701000000 constant mACKSTAT 

35 700100000 constant mSSPlEN \ in ssplconl 

36 700000001 constant mBF \ in ssplstat 

37 700001000 constant mSSPHF \ in pirl 

38 

39 : i2c.init ( -- ) 

40 700001000 ssplconl c! \ Master mode 

41 [ Fey #100 / 1- ] literal sspladd c! \ Set clock frequency to 100 kHz 

42 mSSPHF pirl mclr \ Clear interrupt bit 

43 700011000 trisc mset \ SCL1 on RC3, SDA1 on RC4 

44 700011000 anselc mclr 

45 mSSPlEN ssplconl mset \ Enable hardware 

46 ; 

47 

48 : i2c.close ( -- ) 

49 mSSPlEN ssplconl mclr 

50 mSSPHF pirl mclr 

51 ; 

52 

53 : i2c.wait ( -- ) \ Wait for interrupt flag and clear it 

54 begin mSSPHF pirl mtst until 

55 mSSPHF pirl mclr 

56 ; 

57 

58 : i2c.idle? ( -- f ) 
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59 •/.00011111 ssplcon2 mtst \ ACKEW RCEN REN RSEN SEN 

60 °/ 0 100 ssplstat mtst \ R/~W 

61 or 0 = 

62 ; 

63 

64 : i2c.start ( -- ) \ Send start condition 

65 begin i2c.idle? until 

66 mSSPHF pirl mclr 

67 mSEN ssplcon2 mset 

68 i2c . wait 

69 ; 

70 

71 : i2c.rsen ( -- ) \ Send repeated start condition 

72 mSSPHF pirl mclr 

73 mRSEN ssplcon2 mset 

74 i2c . wait 

75 ; 

76 

77 : i2c.stop ( -- ) \ Send stop condition 

78 mSSPHF pirl mclr 

79 mPEN ssplcon2 mset 

80 i2c . wait 

81 ; 

82 

83 : i2c.buf.full? ( -- f ) 

84 mBF ssplstat mtst 

85 ; 

86 

87 \ Write one byte to bus, leaves ACK bit. 

88 \ A value of 0 indicates ACK was received from slave device. 

89 : i2c.c! ( c -- f ) 

90 begin i2c.buf.full? 0= until 

91 ssplbuf c ! 

92 begin i2c.buf.full? 0= until 

93 begin i2c.idle? until 

94 ssplcon2 c@ mACKSTAT and 

95 ; 

96 

97 \ Send ack bit. 

98 : i2c.ack.seq ( -- ) 

99 mACKEN ssplcon2 mset 

100 begin mACKEN ssplcon2 mtst 0= until 

101 ; 

102 

103 \ Read one byte and ack for another. 

104 : i2c.c@.ack ( -- c ) 

105 mRCEN ssplcon2 mset 

106 begin i2c . buf . full? until 

107 mACKDT ssplcon2 mclr i2c.ack.seq \ ack 

108 ssplbuf c@ 

109 ; 

110 

111 \ Read one last byte . 

112 : i2c.c@.nack ( -- c ) 

113 mRCEN ssplcon2 mset 

114 begin i2c . buf . full? until 

115 mACKDT ssplcon2 mset i2c.ack.seq \ nack 

116 ssplbuf c@ 

117 ; 

118 

119 \ Address slave for writing, leaves true if slave ready. 

120 : i2c . addr . write ( 7-bit-addr -- f ) 

121 1 lshift 1 invert and \ Build full byte with write-bit as 0 

122 i2c . start i2c . c ! 0= 

123 ; 

124 

125 \ Address slave for reading, leaves true if slave ready. 

126 : i2c.addr.read ( 7-bit-addr -- f ) 

127 1 lshift 1 or \ Build full byte with read-bit as 1 

128 i2c . start i2c . c ! 0= 

129 ; 
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130 

131 \ Detect presence of device, leaving true if device present, 0 otherwise. 

132 \ We actually fetch a byte if the slave has acknowledged, then discard it. 

133 : i2c.ping? ( 7-bit-addr -- f ) 

134 i2c.addr.read if i2c.c@.nack drop true else false then 

135 ; 


11.2 PIC24FV32KA30X 


1 \ i2c-base-pic24fv32ka30x.txt 

2 \ Low-level words for I2C master on PIC24FV32KA302 and KA301 

3 \ 

4 \ Modelled on i2c-base.txt for PIC18, i2c-twi.frt from amforth 

5 \ the Microchip PIC24 Family Reference Manual 

6 \ and the datasheet for PIC24FV32KA304 family. 

7 \ Peter J. 2015-09-23 

8 

9 -i2c-base 

10 marker -i2c-base 

11 hex ram 

12 

13 \ Registers related to I2C operation of MSSP1 


14 

$0086 

constant 

ifsl 

15 

$0200 

constant 

i2clrcv 

16 

$0202 

constant 

i2cltrn 

17 

$0204 

constant 

i2clbrg 

18 

$0206 

constant 

i2clcon 

19 

$0208 

constant 

i2clstat 

20 

$020a 

constant 

i2cladd 

21 

$020c 

constant 

i2clmsk 

22 

$02c8 

constant 

trisb 

23 

$02ca 

constant 

portb 

24 

$02cc 

constant 

latb 

25 

$02ce 

constant 

odeb 

26 

$04e2 

constant 

ansb 

27 

$0770 

constant 

pmdl 


28 

29 \ Masks for bits 

30 $8000 constant mI2CEN \ in i2clcon 

31 °/«000001 constant mSEN 

32 # /o000010 constant mRSEN 

33 # /o000100 constant mPEN 

34 # /o001000 constant mRCEN 

35 °/«010000 constant mACKEN 

36 °/«100000 constant mACKDT 

37 $8000 constant mACKSTAT \ in i2clstat 

38 $4000 constant mTRSTAT 

39 $0400 constant mBCL 

40 $0080 constant mlWCOL 

41 $0040 constant mI2C0V 

42 # /o0001 constant mTBF 

43 # /o0010 constant mRBF 

44 ®/o0010 constant mMI2CHF \ in ifsl 

45 

46 $0100 constant mRB8 \ SCL1 on RB8 

47 $0200 constant mRB9 \ SDA1 on RB9 

48 

49 : i2c.init ( -- ) 

50 $80 pmdl mclr \ Enable the I2C1 module 

51 [ Fey #100 / Fey #10000 / - 1- ] literal i2clbrg c! \ Set clock to 100 kHz 

52 mMI2CHF ifsl mclr \ Clear interrupt bit for master operation 

53 7,1100000000 trisb mset \ SCL1 on RB8 , SDA1 on RB9 

54 7,1100000000 odeb mset 

55 mI2CEN i2clcon mset \ Enable hardware 
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56 ; 

57 

58 : i2c.close ( -- ) 

59 mI2CEN i2clcon mclr 

60 mMI2CHF ifsl mclr 

61 ; 

62 

63 : i2c.bus.reset ( -- ) 

64 \ Manually reset the slave devices. 

65 \ For use when a slave just won’t let SDA1 go. 

66 i2c.close 

67 mRB9 trisb mset \ leave SDA1 float 

68 mRB9 odcb mset 

69 mRB8 trisb mclr \ drive SCL1 with digital output 

70 mRB8 odcb mset 

71 9 for 

72 mRB8 latb mclr 1 ms 

73 mRB8 latb mset 1 ms 

74 next 

75 \ stop condition 

76 mRB8 latb mclr 

77 mRB9 trisb mclr 

78 mRB9 latb mclr 1 ms 

79 mRB8 latb mset 

80 mRB9 latb mset 1 ms 

81 \ release bus 

82 mRB8 trisb mset 

83 mRB9 trisb mset 

84 ; 

85 

86 : i2c.wait ( -- ) \ Wait for interrupt flag and clear it 

87 begin mMI2CHF ifsl mtst until 

88 mMI2CHF ifsl mclr 

89 ; 

90 

91 : i2c.idle? ( -- f ) 

92 7o00011111 i2c 1 con mtst \ ACKEN RCEN REN RSEN SEN 

93 0 = 

94 ; 

95 

96 : i2c.start ( -- ) \ Send start condition 

97 begin i2c.idle? until 

98 mMI2CHF ifsl mclr 

99 mSEN i2clcon mset 

100 i2c . wait 

101 ; 

102 

103 : i2c.rsen ( -- ) \ Send repeated start condition 

104 mMI2CHF ifsl mclr 

105 mRSEN i2clcon mset 

106 i2c . wait 

107 ; 

108 

109 : i2c.stop ( -- ) \ Send stop condition 

110 mMI2CHF ifsl mclr 

111 mPEN i2clcon mset 

112 i2c . wait 

113 ; 

114 

115 : i2c . tbuf . f ull ? ( -- f ) 

116 mTBF i2clstat mtst 

117 ; 

118 

119 : i2c . rbuf . f ull ? ( -- f ) 

120 mRBF i2clstat mtst 

121 ; 

122 

123 \ Write one byte to bus, leaves ACK bit. 

124 \ A value of 0 indicates ACK was received from slave device. 

125 : i2c.c! ( c -- f ) 

126 begin i2c.tbuf.full? 0= until 
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127 

128 

129 

130 

131 

132 

133 

134 

135 

136 

137 

138 

139 

140 

141 

142 

143 

144 

145 

146 

147 

148 

149 

150 

151 

152 

153 

154 

155 

156 

157 

158 

159 

160 
161 
162 

163 

164 

165 

166 

167 

168 

169 

170 

171 

172 

173 

174 

175 


mMI2C1IF if s1 mclr 
i2cltrn c! 

\ We wait for the interrupt because just waiting for the buffer 
\ to be empty is unreliable if we look too soon. 
i2c.wait 

begin i2c.idle? until 
i2clstat @ mACKSTAT and 


\ Send ack bit . 

: i2c.ack.seq ( -- ) 
mACKEN i2clcon mset 

begin mACKEN i2clcon mtst 0= until 

\ Read one byte and ack for another. 

: i2c . c@ . ack ( -- c ) 
mRCEN i2clcon mset 
begin i2c.rbuf.full? until 
mACKDT i2clcon mclr i2c.ack.seq \ ack 
i2clrcv c@ 


\ Read one last byte . 
i2c.c@.nack ( -- c ) 
mRCEN i2clcon mset 
begin i2c.rbuf.full? until 
mACKDT i2clcon mset i2c.ack.seq \ nack 
i2clrcv c@ 


\ Address slave for writing, leaves true if slave ready. 

: i2c.addr.write ( 7-bit-addr -- f ) 

1 lshift 1 invert and \ Build full byte with write-bit as 0 
i2c.start i2c . c ! 0= 


\ Address slave for reading, 
: i2c.addr.read ( 7-bit-addr 
1 lshift 1 or \ Build full 
i2c.start i2c . c ! 0= 


leaves true if slave ready 
-- f ) 

byte with read-bit as 1 


\ Detect presence of device, 

\ leaving true if device present, 0 otherwise. 

\ We actually fetch a byte if the slave has acknowledged. 
: i2c.ping? ( 7-bit-addr -- f ) 

i2c.addr.read if i2c.c@.nack drop true else false then 


11.3 ATmega328P 


1 \ i2c-base-avr.txt 

2 \ Low-level words for TWI/I2C on Atmega328P. 

3 \ 

4 \ Modelled on i2c-twi.frt from amforth, 

5 \ i2c_base.txt for FlashForth on PIC18 

6 \ and the Atmel datasheet , of course . 

7 \ Peter J. 2014-10-27 

8 

9 -i2c-base 

10 marker -i2c-base 

11 hex ram 

12 
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13 \ Two-Wire-Interface Registers 

14 $b8 constant TWBR 

15 $b9 constant TWSR 

16 $bb constant TWDR 

17 $bc constant TWCR 

18 

19 \ Bits in the Control Register 

20 710000000 constant mTWINT 

21 # /.01000000 constant mTWEA 

22 700100000 constant mTWSTA 

23 700010000 constant mTWSTO 

24 700001000 constant mTWWC 

25 700000100 constant mTWEN 

26 700000001 constant mTWIE 

27 

28 : i2c.init ( -- ) \ Set clock frequency to 100kHz 

29 °/,ll TWSR mclr \ prescale value = 1 

30 [ Fey #100 / #16 - 2/ ] literal TWBR c! 

31 mTWEN TWCR mset 

32 ; 

33 

34 : i2c.wait ( -- ) \ Wait for operation to complete 

35 \ When TWI operations are done, the hardware sets 

36 \ the TWINT interrupt flag, which we will poll. 

37 begin TWCR c@ mTWINT and until 

38 ; 

39 

40 : i2c.start ( -- ) \ Send start condition 

41 [ mTWINT mTWEN or mTWSTA or ] literal TWCR c! 

42 i2c . wait 

43 ; 

44 

45 : i2c.rsen ( -- ) \ Send repeated start condition 

46 i2c.start \ AVR doesn’t distinguish 

47 ; 

48 

49 : i2c.stop ( -- ) \ Send stop condition 

50 [ mTWINT mTWEN or mTWSTO or ] literal TWCR c! 

51 ; 

52 

53 \ Write one byte to bus, returning 0 if ACK was received, -1 otherwise. 

54 : i2c.c! ( c -- f ) 

55 i2c.wait \ Must have TWINT high to write data 

56 TWDR c ! 

57 [ mTWINT mTWEN or ] literal TWCR c! 

58 i2c . wait 

59 \ Test for arrival of an ACK depending on what was sent. 

60 TWSR c@ $f8 and $18 xor 0= if 0 exit then \ SLA + W 

61 TWSR c@ $f8 and $28 xor 0= if 0 exit then \ data byte 

62 TWSR c@ $f8 and $40 xor 0= if 0 exit then \ SLA + R 

63 -1 \ Something other than an ACK resulted 

64 ; 

65 

66 \ Read one byte and ack for another. 

67 : i2c.c@.ack ( -- c ) 

68 [ mTWINT mTWEN or mTWEA or ] literal TWCR c! 

69 i2c . wait 

70 TWDR c@ 

71 ; 

72 

73 \ Read one last byte . 

74 : i2c.c@.nack ( -- c ) 

75 [ mTWINT mTWEN or ] literal TWCR c! 

76 i2c . wait 

77 TWDR c@ 

78 ; 

79 

80 \ Address slave for writing, leaving true if slave ready. 

81 : i2c.addr.write ( 7-bit-addr -- f ) 

82 1 lshift 1 invert and \ Build full byte with write-bit as 0 

83 i2c.start i2c.c! if false else true then 



84 

85 

86 

87 

88 

89 

90 

91 

92 

93 

94 

95 

96 

97 
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\ Address slave for reading, leaving true if slave ready. 
: i2c.addr.read ( 7-bit-addr -- f ) 

1 lshift 1 or \ Build full byte with read-bit as 1 
i2c . start i2c . c ! if false else true then 


\ Detect presence of device, leaving true if slave responded. 

\ If the slave ACKs the read request, fetch one byte only. 

: i2c.ping? ( 7-bit-addr -- f ) 

1 lshift 1 or \ Build full byte with read-bit as 1 

i2c.start i2 c.c! 0= if i2c.c@.nack drop true else false then 


11.4 Notes on using the words 

• The word i2c. init is used to set up the I 2 C master peripheral for further activities. 

• I 2 C conversations begin by addressing a slave device for either reading or writing. 
The words i2c. addr. read and i2c . addr .write are provided for this waking of 
the slave. They leave a flag on the stack to indicate whether the slave device 
acknowledged being addressed. If the slave device responded appropriately, you 
may proceed to read or write bytes. 

• There are two words for reading a byte from the bus. i2c. c@. ack reads a byte and 
asserts an acknowledge (ACK) to indicate to the slave device that another byte will 
be read subsequently. i2c.c@.nack reads a byte and asserts a NACK to indicate 
to the slave that no more bytes are wanted. 

• The word to sending a byte to the slave device is i2c. c!. This word leaves a flag 
to indicate the state of the ACK bit following the action of sending the byte. If the 
slave asserted ACK, the flag will be 0. You may drop this flag if it not of interest 
to you. 

• There are lower-level words i2c. start, i2c.rsen and i2c.stop to assert start, 
restart and stop conditions respectively. These are used within the higher-level 
words mentioned above. 

• The utility word i2c.ping? attempts to address a slave and read a byte. It leaves 
true if the slave responds, else false. 

• Sometimes when tinkering with a new I 2 C device, you can get into a state of con¬ 
fusion such that the slave device will end up in some intermediate state waiting 
for clock signals. 3 In this state, the slave device will no longer respond in a way 
that the master peripheral understands. Rather than cycle the power to reset the 
slave device, it may be convenient to force the clocking of the data bits through the 
bus and get the slave device back into an idle state. The word i2c. reset .bus (in 
i2c-base-pic24fv32ka30x.txt) is provided to automate this forced clocking. 


3 This happens more often than I would like to admit. 
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11.5 Detecting I2C devices 

Building on the base words for a particular microcontroller, the following program works 
on all of the microcontrollers discussed in this tutorial guide. It is convenient to run this 
program to to see if the device of interest is responding. There’s no point trying to have 
a conversation with a device that doesn’t respond to being addressed. 

1 \ i2c-detect.txt 

2 \ Detect presence of all possible devices on I2C bus. 

3 \ Only the 7 bit address schema is supported. 

4 \ 

5 \ Copied from amForth distribution (lib/hardware/) 

6 \ and lightly edited to suit FlashForth 5.0 on AVR. 

7 \ Builds upon i2c-base-xxxx.txt and doloop.txt. 

8 \ Peter J. 2014-10-27 

9 

10 -i2c-detect 

11 marker -i2c-detect 

12 

13 \ not all bitpatterns are valid 7bit i2c addresses 

14 : i2c.7bitaddr? ( a -- f) $7 $78 within ; 

15 

16 : i2c. detect ( -- ) 

17 base 0 hex 

18 \ header line 

19 cr 5 spaces $10 0 do i 2 u.r loop 

20 $80 0 do 

21 i $0f and 0= if 

22 cr i 2 u.r [char] : emit space 

23 then 

24 i i2c.7bitaddr? if 

25 i i2c.ping? if \ does device respond? 

26 i 2 u . r 

27 else 

28 . " " 

29 then 

30 else 

31 . " " 

32 then 

33 loop 

34 cr base ! 

35 ; 

36 

37 \ With a lone Microchip TC74A0 sitting on the bus, 

38 \ the output looks like 

39 \ i2c.init ok<$,ram> 

40 \ i2c.detect 

41 \ 00 01 02 03 04 05 06 07 08 09 0a 0b 0c Od Oe Of 

42 \ 00 : 

43 \ 10 : -- -- -- -- -- 

44 \ 20 : -- -- -- -- -- 

45 \ 30 : -- -- -- -- -- 

46 \ 40 : -- -- -- -- -- 

47 \ 50 : -- -- -- -- -- 

48 \ 60 : — — — — — 

49 \ 70 : -- -- -- -- -- 

50 \ ok<$ , ram> 

51 \ i2c.stop ok<$,ram> 
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12 Using I2C to get temperature measurements 

Using the words in i2c-base-k22. txt to control the MSSP peripheral in master mode, 
one may talk to the TC74A5 temperature measurement chip on the PICDEM 2 PLUS 
and report sensor temperature. 


\ Read temperature from TC74 on PICDEM2+ board with PIC18F46K22-I/P. 
\ Modelled on Mikael Nordman’s i2c_tcn75.txt. 

\ This program requires i2c-base-k22.txt to be previously loaded, 
-read -1c74 
marker -read-tc74 

'/olOOHOl constant addr-TC74A5 \ 7-bit address for the chip 
: tc74-init ( -- ) 

\ Selects the temperature register for subsequent reads. 
addr-TC74A5 i2c.addr.write if 0 i2c.c! drop then i2c.stop 

: sign-extend ( c -- n ) 

\ If the TC74 has returned a negative 8-bit value, 

\ we need to sign extend to 16-bits with ones. 
dup $7f > if $ff80 or then 

: degrees® ( -- n ) 

\ Wake the TC74 and receive its register value . 

addr-TC74A5 i2c.addr.read if i2c.c®.nack sign-extend else 0 then 

: tc74-main ( -- ) 
i2c.init 
tc74-init 
begin 

degrees® . 

#1000 ms 
key? until 


\ Now, report temperature in degrees C 
\ while we warm up the TC74 chip with our fingers . . . 
decimal tc74-main 


With a Saleae Logic Analyser connected to the pins of the TC74A5, we can see the I 2 C 
signals as a result of calling the tc74-init word. 



A little later on, the degrees® word is invoked. The returned binary value of ObOOOlOlOl 
corresponds to the very pleasant 21°C that exists in the back shed as this text is being 
written. 
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13 Making high-resolution voltage measurements 

The Microchip MCP3422 is a SA-ADC that can connected via I 2 C port. This neat little 
converter can measure voltages with a resolution of 18 bits (at the lowest data rate of 3.75 
samples per second) and includes a programmable gain amplifier [10]. Being available in 
a surface-mount package only, it was convenient to use a prebuilt evaluation board, the 
green board between the home-built FlashForth demo board and the fixed-voltage supply 
board. The MCP3422 evaluation board is connected to and powered from the I 2 C header 
on the FlashForth demo board. Separately, the fixed-voltage supply board provides the 
measurement voltage to channel 1 of the MCP3422 via a potentiometer that is set to give 
1.024 V, according to my (fairly cheap) multimeter. 



\ mcp3422-2016.txt 
\ Play with mcp3422 eval board. 

\ PJ , 21- Oct-2013 

\ 28-Apr-2014 PIC18F26K22 version 

\ 27-Jan-2016 update to use latest i2c words 

\ Needs i2c-base-k22.txt and math.txt (to get m*/) . 

-mcp3422 
marker -mcp3422 

$68 constant addr-mcp3422 \ 7-bit address 
: mcp3422-init ( — ) 

\ $9c is config for 18-bit continuous conversions of ch 1 
addr-mcp3422 i2c.addr.write if $9c i2c.c ! drop then i2c.stop 


mcp3422@ ( -- d f ) \ Read the 18-bit result as 3 bytes 
addr-mcp3422 i2c.addr.read 
if 

i2c.c@.ack \ only 2 bits in first byte 

dup $3 > if $fffa or then \ sign-extend to full cell 

i2c.c@.ack $8 lshift i2c.c@.ack or \ next two bytes into one cell 

swap \ leave double result 

i2c.c@.nack $80 and 0= \ leave true if result is latest 

else 

0 0 0 \ device did not ack on address 
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then 


microvolts ( dl -- d2 ) 

\ The least-significant bit corresponds to 15.625 microvolts 
#125 #8 m*/ 


(d.3) ( d — ) 

swap over dabs 

<# # # # [char] . hold #s rot sign #> 

report ( d f -- ) \ Assuming decimal , print millivolt value 
cr if . " new " else . " old " then 
microvolts (d.3) type space ." mV " 

mcp3422-run ( — ) 
decimal 

i2c.init mcp3422-init 
begin 

mcp3422@ report 
#1000 ms 
key? until 
hex 


Notes on this program: 

• mcp3422-run is the top-level word that initializes the hardware, then periodically 
reads the MCP3422 data and reports the voltage (in millivolts) to the user terminal. 
The program runs until a key is pressed. 

• The converted value is read from the MCP3422 as and 18-bit value in 2-complement 
format. The word mcp3422@ reads the data as three bytes from the I 2 C port and 
then shuffles it into a double-cell value that is left on the stack, along with a flag to 
indicate whether the value sent by the MCP3422 happened to be the latest data. If 
the MCP3422 did not respond to being addressed, zeros will be left on the stack in 
place of the expected data. 

• The value is scaled to microvolts and then the resultant double value is output using 
the pictured numeric output to have 3 decimal places so that it looks like a millivolt 
reading. Several lines from the terminal look like the following: 

new 1028.031 mV 
new 1028.062 mV 
new 1028.046 mV 


This program builds upon the i2c-base-k22 words in order to communicate with 
the MCP3422. The code for scaling of the measured data requires the mixed-scale 
word m*/ from the hie math.txt provided by FlashForth. 
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14 An I2C slave example 

The MSSP in the PIC18F26K22 can also be used in slave mode. Here, the FlashForth 
demo board is presented as an I 2 C slave device to an Aardvark serial interface, acting as 
master. The UART communication is provided by a Future Technology Devices Interna¬ 
tional USB TTL-serial cable. 

The core of the program is the i2c_service word which is invoked each time a serial-port 
event is flagged by the SSPIF bit in the PIR1 flag register. This word is an implementation 
of the state look-up approach detailed in the Microchip Application Note AN734 [11]. The 
rest of the program is there to provide (somewhat) interesting data for the I 2 C master 
to read and to do something (light a LED) when the master writes suitable data to the 
slave. 


-i2c- slave 
marker -i2c-slave 

\ Make the FlashForth 26K22 demo board into an I2C slave. 
\ An I2C master can read and write to a buffer here, 

\ the least - signif icant bit of the first byte controls 
\ the LED attached to pin RB0. 

\ 

\ Needs core.txt loaded. 

$ff81 constant portb 
$ff82 constant portc 
$ff8a constant latb 
$ff93 constant trisb 
$ff94 constant trisc 
$ff3a constant anselc 

: led_on ( -- ) 

7,00000001 latb mset 

: led.off ( -- ) 

7,00000001 latb mclr 

: err_led_on ( -- ) 

7,00000010 latb mset 

: err_led_off ( -- ) 

7,00000010 latb mclr 


\ Establish a couple of buffers in RAM, together with index variables, 
ram 

8 constant buflen 

\ Receive buffer for incoming I2C data, 
create rbuf buflen allot 
variable rindx 
: init_rbuf ( -- ) 
rbuf buflen erase 
0 rindx ! 

: incr_rindx ( — ) \ increment with wrap-around 
rindx @ 1 + 

dup buflen = if drop 0 then 
rindx ! 

: save_to_rbuf ( c -- ) 
rbuf rindx 0 + c ! 
incr_rindx 


\ Send buffer with something interesting for the I2C master to read. 
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51 create sbuf buflen allot 

52 variable sindx 

53 : incr_sindx ( -- ) \ increment with wrap-around 

54 sindx 0 1 + 

55 dup buflen = if drop 0 then 

56 sindx ! 

57 ; 

58 : init_sbuf ( -- ) \ fill with counting integers, for interest 

59 buflen 

60 for 

61 rO 1 + 

62 sbuf rO + c ! 

63 next 

64 0 sindx ! 

65 ; 

66 

67 \ I2C-related definitions and code 

68 $ffc5 constant sspcon2 

69 $ffc6 constant sspconl 

70 $ffc7 constant sspstat 

71 $ffc8 constant sspadd 

72 $ffc9 constant sspbuf 

73 $ff9e constant pirl 

74 

75 \ PIR1 bits 

76 7.00001000 constant sspif 

77 

78 \ SSPSTAT bits 

79 # / 0 00000001 constant bf 

80 # / 0 00000100 constant r_nw 

81 # / 0 00001000 constant start_bit 

82 # / 0 00010000 constant stop_bit 

83 # /.00100000 constant d_na 

84 # /.01000000 constant eke 

85 # /.10000000 constant smp 

86 

87 d_na start_bit or r_nw or bf or constant stat_mask 

88 

89 \ SSPC0N1 bits 

90 y o 00010000 constant ckp 

91 # / 0 00100000 constant sspen 

92 # / 0 01000000 constant sspov 

93 # / 0 10000000 constant wcol 

94 

95 \ SSPC0N2 bits 

96 yOOOOOOOl constant sen 


97 






98 

i2c_init ( -- ) 





99 

°/* 11000 anselc mclr 

\ 

enable digital-in o 

n RC3 

,RC4 (SCL1 ,SDA1) 

100 

°/ 0 00011000 trisc mset 

\ RC3 == SCL RC4 == SDA 



101 

0 /oOOOOOHO sspconl c 

I 

\ Slave mode with 7 

-bit 

address 

102 

sen sspcon2 mset \ 

Cl 

ock stretching enabled 


103 

smp sspstat mset \ 

SI 

ew-rate disabled 



104 

$52 1 lshift sspadd 

c 

! \ Slave address 



105 

sspen sspconl mset 

\ 

Enable MSSP periphe 

r al 


106 






107 






108 

release_clock ( -- 

) 




109 

ckp sspconl mset 





110 






111 






112 

i2c_service ( -- ) 





113 

\ Check the state of 

the I2C peripheral 

and r 

eact . 

114 

\ See App Note 734 

f 0 

r an explanation of 

the 

5 states . 

115 

\ 





116 

\ State 1: i2c writ 

e 

operation , last byt 

e was 

address . 

117 

\ D_nA =0 , S = 1 , R_nW 

=0 

to 

ii 



118 

sspstat c@ stat.mas 

k 

and 7,00001001 = 



119 

if 





120 

sspbuf @ drop 





121 

init _rbuf 
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122 release.clock 

123 exit 

124 then 

125 \ State 2: i2c write operation, last byte was data. 

126 \ D_nA = 1 , S = 1 , R_nW = 0 , BF = 1 

127 sspstat c@ stat_mask and °/ 0 00101001 = 

128 if 

129 sspbuf c@ save_to_rbuf 

130 release_clock 

131 exit 

132 then 

133 \ State 3: i2c read operation, last byte was address. 

134 \ D_nA =0 , S = 1 , R_nW = 1 

135 sspstat c@ °/ 0 00101100 and °/ 0 00001100 = 

136 if 

137 sspbuf c@ drop 

138 0 sindx ! 

139 wool sspconl mclr 

140 sbuf sindx 0 + c@ sspbuf c! 

141 release.clock 

142 incr_sindx 

143 exit 

144 then 

145 \ State 4: i2c read operation, last byte was outgoing data. 

146 \ D_nA = 1 , S = 1 , R_nW = l , BF = 0 

147 sspstat c@ stat_mask and °/ 0 00101100 = 

148 ckp sspconl mtst 0= 

149 and 

150 if 

151 wool sspconl mclr 

152 sbuf sindx @ + c@ sspbuf c! 

153 release_clock 

154 incr_sindx 

155 exit 

156 then 

157 \ State 5: master NACK, slave i2c logic reset. 

158 \ From AN734: D_nA=l, S=1, BF=0, CKP=1, however, 

159 \ we use just D_nA=l and CKP=1, ignoring START bit. 

160 \ This is because master may have already asserted STOP 

161 \ before we service the final NACK on a read operation. 

162 d_na sspstat mtst 0 > ckp sspconl mtst 0 > and 

163 stop_bit sspstat mtst or 

164 if 

165 exit \ Nothing needs to be done. 

166 then 

167 \ We shouldn’t arrive here... 

168 err_led_on 

169 cr . " Error " 

170 ." sspstat " sspstat c@ u. 

171 ." sspconl " sspconl c@ u. 

172 ." sspcon2 " sspcon2 c@ u. 

173 cr 

174 begin again \ Hang around until watch-dog resets MCU. 

175 ; 

176 

177 

178 : init ( -- ) 

179 '/oOOOOOOll trisb mclr \ want RB0,RB1 as output pins 

180 init_rbuf 

181 init_sbuf 

182 i2c_init 

183 led_on err_led_on #200 ms led_off err_led_off 

184 ; 

185 

186 : main ( -- ) 

187 cr . " Start I2C slave " 

188 init 

189 begin 

190 sspif pirl mtst 

191 if 

192 


sspif pirl mclr 
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193 

i2c_service 

194 

then 

195 

rbuf c@ °/»00000001 and 

196 

if led_on else led_off 

197 

cwd 

198 

key? until 

199 ; 


200 


201 \ 

’ main is turnkey 


With a Saleae Logic Analyser connected, we can see the I 2 C signals as a result of writing 
the byte 0x01 to turn on the LED. The following figure shows the data and clock signals 
from the time that the master asserts the START condition (green circle) until it asserts 
the STOP condition (as indicated by the red square). 



The clock frequency is 100kHz and there is a 138 fi s gap between the ninth clock pulse of 
the address byte and the start of the pulses for the data byte. This gives an indication of 
the time needed to service each SSPIF event. 

A little later on, the Aardvark reads two bytes from the bus, as shown here. 



Zooming in, to show the finer annotation, the same signals are shown below. 



Again, the inter-byte gap is 138 /zs resulting in about 200 /zs needed to transfer each byte. 
This effective speed of 5 kbytes/s should be usable for many applications, since the I 2 C 
bus is typically used for low speed data transfer. 

Notes on this program: 

• Need to load core.txt before the source code of the i2c-slave.txt. 

• Slave examples found in documentation on the Web usually have the service function 
written in the context of an interrupt service routine. The MSSP can be serviced 
quite nicely without resorting to the use of interrupts, however, you still have to 
check and clear the SSPIF bit for each event. 

• The implementation of the test for State 5 (Master NACK) is slightly different to 
that described in AN734 because it was found that the master would assert an I 2 C 
bus stop after the final NACK of a read operation but before the MCU could service 
the SSPIF event. This would mean that STOP was the most recent bus condition 
seen by the MSSP and the START and STOP bits set to reflect this. In the figures 
shown above, there is only about 12 /zs between the ninth clock pulse for the second 
read data byte and the Aardvark master asserting the STOP condition on the bus. 
This period is very much shorter than the (approx.) 140 /zs period needed by the 
slave firmware to service the associated SSPIF event. 
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15 Speed of operation — bit banging 

All of this nice interaction and convenience has some costs. One cost is the number of 
MCU instruction cycles needed to process the Forth words. To visualize this cost, the 
following program defines a word blink-forth which toggles an 10 pin using the high- 
level FlashForth words that fetch and store bit patterns into the port latch register. An 
alternative word blink-asm uses assembler instructions to achieve an equivalent effect, 
but faster, and a third word blink-bits uses the FlashForth bitO: and bitl: words to 
create high-level bit-manipulation words that also achieve full machine speed. 

15.1 PIC18F26K22 


1 -speed-test 

2 marker -speed-test 

3 \ Waggle RBI as quickly as we can, in both high- and low-level code. 

4 \ Before sending this file, we should send asm.txt so that we have 

5 \ the clrwdt, word available. We also need bit.txt. 

6 

7 $ff8a constant latb 

8 $ff93 constant trisb 

9 

10 : initRBl 

11 7,10 trisb mclr \ RBI as output 

12 7,10 latb mclr \ initially known state 

13 ; 

14 


15 

\ 

high-level 

bit 


fiddling, presumably slow 

16 


blink -forth 

( 

- 

- ) 

17 


initRB1 




18 


begin 




19 


7.10 latb 

c ! 

0 

latb c! \ one cycle, on and off 

20 


7.10 latb 

c ! 

0 

latb c ! 

21 


7.10 latb 

c ! 

0 

latb c ! 

22 


7.10 latb 

c ! 

0 

latb c ! 

23 


cwd \ We 

have 

to kick the watch dog ourselves 

24 


again 




25 

; 





26 






27 

\ 

low-level bit 

fiddling, via assembler 


28 : blink-asm ( -- ) 

29 initRBl 

30 [ 

31 begin , 

32 latb 1 a, bsf , latb 1 a, bcf , \ one cycle , on and off 

33 latb 1 a, bsf, latb 1 a, bcf, 

34 latb 1 a, bsf, latb 1 a, bcf, 

35 latb 1 a, bsf, latb 1 a, bcf, 

36 clrwdt, \ kick the watch dog 

37 again , 

38 ] 

39 ; 

40 

41 \ high-level bit fiddling with named bits 

42 latb #1 bitl: RBl-hi inlined 

43 latb #1 bitO: RBl-lo inlined 


44 : 

blink-bits ( -- 

) 

45 

initRBl 


46 

begin 


47 

RBl-hi RBl-lo 

\ one 

48 

RBl-hi RBl-lo 


49 

RBl-hi RBl-lo 


50 

RBl-hi RBl-lo 


51 

cwd 
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again 


Notes on this program: 

• We have had to worry about clearing the watch-dog tinier. In the early examples, 
the FlashForth interpreter was passing through the pause state often enough to keep 
the watch-dog happy. The words in this example give the FlashForth interpreter no 
time to pause so we are responsible for clearing the watch-dog timer explicitly. 

• In the source code conhg hie for the specific MCU, the watch-dog timer postscale 
is set to 256. With a 31.25 kHz oscillator frequency, this leads to a default timeout 
period of a little over 1 second (32 /zs x 128 x 256). 

• For the PIC18 MCU, the internal oscillator of 16 MHz was multiplied by the PLL to 
get 64 MHz oscillator driving the MCU. With 4 clock cycles per instruction cycle, 
this gave an instruction period Tqy = 62.5 ns. Current consumption by the micro¬ 
controller was about 14 mA, roughly double the value when the interpreter is not 
doing much, just waiting for input. 


• The screen image on the left shows the output signal for running the high-level 
blink-forth word while the image on the right uses the assembler words. 



• For the blink-forth word, one on+off cycle of the LED executes in 6 words and 
is seen (in the oscilloscope record) to require about 50 instruction cycles. So, on 
average, each of these threaded Forth words is executed in about 8 MCU instruc¬ 
tion cycles. Note that this overhead includes the cost of using 16-bit cells for the 
data. Extra machine instructions are used to handle the upper bytes. In other 
applications, where we actually want to handle 16-bit data, this will no longer be a 
penalty. 

• The assembler version has no overhead and the cycle time for the MCU instructions 
defines the period of the output signal. One on-off cycle requires 2 instructions so 
we see a short 125 ns period. This is fast enough that the capacitive loading on the 
output pin is noticeable in the oscilloscope trace. Also, the time required for the 
machine instructions to clear the watch-dog timer and the instruction jump back to 
the start of the loop now shows up clearly in the oscilloscope record. 
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• The oscilloscope record for the blink-bits word is shown here. 


RIGOL STOP f Q 2.40U 


|a 


Curfi= 1.81us 



CurB=2.18us 



AX=368ns 

: : 

[ 


1/AX: 2.7 17MH 2 

[A (1: A A fl J\ 

fr A 

fl .. .IWA.A.. .. 

| ; J| : 1 1 ! 

■ 1 : : \\ 

m 


Ld « u u VyJ v 

ill 

illllljpiljj 

i ' i'' 

j 

_;_;___1... 


^ i....i.... i .... i .... 1 


MS IB 2.000 Time 200.0ns ©>2.000us 


With the bit-manipulation words RBl-hi and RBl-lo being inlined, they also achieve 
full machine speed because the generated code is essentially the same as for blink-asm. 


15.2 PIC24FV32KA302 


-speed-test 
marker -speed-test 

\ For the PIC24FV32KA302, waggle RB15 as quickly as we can, 
\ in both high- and low-level code. 

\ Remember to load bit.txt before this file. 

$02c8 constant trisb 
$02ca constant portb 
$02cc constant latb 
$02ce constant odcb 

1 #15 lshift constant bitl5 

: initRB15 

bitl5 trisb mclr \ RB15 as output 
bitl5 latb mclr \ initially known state 


high-level bit 

fiddling 

presumably slow 

blink-forth ( - 

- ) 


initRB15 



begin 



bitl5 latb ! 

0 latb ! 

\ one cycle , on and off 

bitl5 latb ! 

0 latb ! 


bitl5 latb ! 

0 latb ! 


bitl5 latb ! 

0 latb ! 


cwd \ We have 

to kick 

the watch dog ourselves 

again 




low -level 

bit 

fiddling, 

via assembler 

blink - asm 

c - 

- ) 



initRB15 
[ 


begin . 


#15 

latb 

bset , 

#15 

latb 

bclr 

#15 

latb 

bset , 

#15 

latb 

bclr 

#15 

latb 

bset , 

#15 

latb 

bclr 

#15 

latb 

bset , 

#15 

latb 

bclr 

] cwd [ 

\ kick 

the 

watch 

dog 


again . 


\ one cycle , on 


and 


off 
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] 


\ high-level bit fiddling with named bits 
latb #15 bitl: RB15-hi inlined 
latb #15 bitO: RB15-lo inlined 
: blink-bits ( -- ) 
initRB15 
begin 

RB15-hi RB15-lo \ one cycle 
RB15-hi RBI5-lo 
RB15-hi RBI5-lo 
RB15-hi RBI5-lo 
cwd 
again 


Notes on this program: 

• The order of the assembler arguments is bit-number register-address op-code. This 
is different to that seen in the PIC18 version of the program. 

• The MCU was configured for running off its internal 8 MHz oscillator with the 
4x PLL active and a 1:1 postscaling. This resulted in an instruction cycle period 
Toy = 62.5 ns. 

• The screen image on the left shows the output signal for running the high-level 
blink-forth word while the image on the right uses the assembler words. 



RIGOL STOP » 




.Vi.vi_ i_ 



Q 968mU 

Cur ft 

-8.00ns 

CurB 

116ns 

AX 

124ns 

1/AX 

8.065MH 2 


7 1 :!/ 1 ; / \ - 1 

J J \j x. V 


Time 1.000us G*0.0000s I MUffl 2.00U 


Time 100.0ns 0^0.0000s 


• For the blink-forth word, one on+off cycle of the LED executes in 6 words and 
is seen (in the oscilloscope record) to require about 42 instruction cycles. So, on 
average, each of these threaded Forth words is executed by the 16-bit PIC24 in 
7 MCU instruction cycles. This illustrates a benefit of the 16-bit processor, since 
the 8-bit PIC18F26K22 required 50 MCU instruction cycles (and a correspondingly 
longer time of 3.08 microseconds) for the same effect. 

• The assembler version has no overhead and the cycle time for the MCU instructions 
defines the period of the output signal. One on-off cycle requires 2 instructions so 
we see a short 124 ns period. 

• The oscilloscope record for the blink-bits word is shown here. 
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RIGOL STOP m 5 O 960mU 



\ Curfi=-8.00ns 


j CurB s 116ns 


i AX: 124ns 


i 1/AX:8.065MH 2 

..... j ............ 

i 

lit 1 : l / \ '■ 

i . J 

u u ill lT.L_ 

... \.: LI.. 1:i... 1: A J 

V/ V 

Vj! \J ■ 


j i 

| 

j 


M5iB 2.80U Time 100.0ns 0^0.0000s 


Again, the bit-manipulation words RB15-hi and RB15-lo also achieve full machine 
speed. 

15.3 ATmega328P 


-speed-test 
marker -speed-test 

\ Waggle PB5 as quickly as we can, in both high- and low-level code. 

\ Before sending this file, we should send asm.txt and bit.txt. 

$0024 constant ddrb 

$0025 constant portb \ RAM address 
$0005 constant portb-io \ 10-space address 
1 #5 lshift constant bit5 

: initPB5 

bit5 ddrb mset \ set pin as output 
bit5 portb mclr \ initially known state 

: cwd ( -- ) [ wdr , ] ; inlined \ we might want to reset the watchdog 

\ high-level bit fiddling, presumably slow 
: blink-forth ( -- ) 
initPB5 
begin 


bit 5 

portb 

c ! 

0 

portb 

c! \ one cycle , 

on and off 

bit 5 

portb 

c ! 

0 

portb 

c ! 


bit 5 

portb 

c ! 

0 

portb 

c ! 


bit 5 

portb 

c ! 

0 

portb 

c ! 



cwd 

again 

\ low-level bit fiddling, via assembler 
: blink-asm ( -- ) 
initPB5 
[ 

begin , 


portb-io 

#5 

sbi , 

portb-io 

#5 

cbi , 

\ one cycle , 

on and off 

portb-io 

#5 

sbi , 

portb-io 

#5 

cbi , 



portb-io 

#5 

sbi , 

portb- io 

#5 

cbi , 



portb-io 
wdr , 

#5 

sbi , 

portb- io 

#5 

cbi , 




again , 
] 


\ high-level bit fiddling with named bits 
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portb #5 bitl: PB5-hi inlined 
portb #5 bitO: PB5-lo inlined 
: blink-bits ( -- ) 
initPB5 
begin 

PB5-hi PB5-lo \ one cycle 
PB5-hi PB5-lo 
PB5-hi PB5-lo 
PB5-hi PB5-lo 
cwd 
again 


Notes on this program: 

• Except for names, this code is essentially the same as for the PIC18 and PIC24 
versions of the exercise. FlashForth abstracts away much of the instruction-set 
architecture of the microcontroller, leaving us to focus on twiddling the bits of the 
peripheral hardware. 

• The MCU was configured for running with the 16 MHz crystal, which resulted in a 
machine clock cycle period Tcy — 62.5 ns. 

• The screen image on the left shows the output signal for running the high-level 
blink-forth word while the image on the right uses the assembler words. 


RIGOL STOP W* I 

it:-' t 



-11.0US 
-5.36us 
5.68us 
176.1kHz 


M51B 2.00U 


RIGOL STOP 




f O 960mU 




$ 

Curfl : -752ns 





CurB=-496ns 





1 AX- 256ns 





1/AX=3.906MH2 


ri: i 



n rt 


f | 


U U v_ 

:l j : l 9 

\J 






IKiB 2.00U 



T ime 

200.0ns Oh►©.0000 s 


• For the blink-forth, one on+off cycle of the LED executes in 6 words and is seen (in 
the oscilloscope record) to require about 90 instruction cycles. So, on average, each 
of these threaded Forth words is executed by the 8-bit AVR in 15 MCU instruction 
cycles. 

• The assembler version has no overhead and the cycle time for the MCU instructions 
defines the period of the output signal. One on-off cycle requires 2 instructions 
(sbi and cbi) each requiring 2 clock cycles, so we see a short, quarter-microsecond 
period. 

• The oscilloscope record for the blink-bits word is shown here. 
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It can be seen that the bit-manipulation words PB5-hi and PB5-lo achieve full 
machine speed. 
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16 Driving an Hitachi-44780 LCD controller 

The LCD in the photograph on page 7 was driven with the following code. During the 
development of this example, a lesson was relearned - that of reading the data sheet [12] 
carefully :) 


\ Exercise LCD on PICDEM2+ board. 

\ Remember to load bit.txt before this file, 
-xlcd 

marker -xlcd 


$ff80 constant porta 
$ff89 constant lata 
$ff92 constant trisa 
$ff83 constant portd 
$ff8c constant latd 
$ff95 constant trisd 


\ The 
\ RA1 
\ RA2 
\ RA3 
\ RD0 
\ RD1 
\ RD2 
\ RD3 


LCD is operated in nibble mode . 
= Enable (E) pin 
= Read/Write (RW) pin 
= Register Select (RS) pin 
= DB4 on LCD 
= DB5 
= DB6 
= DB7 


portd constant dataport 
lata #1 bitO: Elo 
lata #1 bitl: Ehi 
lata #2 bitO: RWlo 
lata #2 bitl: RWhi 
lata #3 bitO : RSlo 
lata #3 bitl: RShi 


data-port-in ( — ) 
trisd c@ $0f or trisd c! 


data-port - out ( - - ) 
trisd c@ $f0 and trisd c! 


put-nibble ( c -- ) 

\ Make lower 4 bits of c appear on data port pins. 
$0f and 

dataport c@ $f0 and 
or 

dataport c! 


short-delay ( -- ) 

18 for r@ drop next ; 

Estrobe ( -- ) 

Ehi short-delay Elo 


lcd-getc ( -- c ) 

\ Read the LCD register in two nibbles. 

\ Remember to select the register line before calling this word, 
data-port -in 
RWhi short-delay 

Ehi short-delay dataport c@ #4 lshift Elo short-delay \ high nibble 
Ehi short-delay dataport c@ Elo short-delay \ low nibble 
or \ assemble full byte and leave it on the stack 
RWlo short-delay 
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63 

64 

65 

66 

67 

68 

69 

70 

71 

72 

73 

74 

75 

76 

77 

78 

79 

80 
81 
82 

83 

84 

85 

86 
87 


90 

91 

92 

93 

94 

95 

96 

97 

98 

99 
100 
101 
102 

103 

104 

105 

106 

107 

108 

109 

110 
111 
112 

113 

114 

115 

116 

117 

118 

119 

120 
121 
122 

123 

124 

125 

126 

127 

128 

129 

130 

131 

132 

133 


lcd-ready? ( -- f ) 

\ Read the command register and check busy bit . 
RSlo short-delay 
lcd-getc $80 and 0= 


wait-for-lcd ( -- ) 
begin lcd-ready? cwd until 


lcd-putc ( c -- ) 

\ Write the LCD register in two nibbles. 

\ Remember to select the register line before calling this word, 
dup $f0 and #4 rshift \ high nibble left on top of stack 
data-port-out 
RWlo short-delay 

put-nibble short-delay Estrobe short-delay 
$0f and \ low nibble now left on top of stack 
put-nibble short-delay Estrobe short-delay 
data-port -in 


lcd-clear ( -- ) 
wait -f or - led 
RSlo short-delay 
7 , 00000001 lcd-putc 


led-home ( -- ) 
wait-for-led 
RSlo short-delay 
°/o00000010 lcd-putc 

led-goto ( c -- ) 

\ Set the specified 7-bit data memory address, 
wait-for-led 
RSlo short-delay 

$80 or \ sets the highest bit for the command 
lcd-putc 


led-init ( -- ) 
data-port -in 
Elo RWlo RSlo 

7o00001110 trisa mclr \ RS , RW and E as output 
30 ms \ power-on delay 

\ Begin "initialization by instruction" 

\ Presumably, the LCD is in 8-bit interface mode. 

°/«0011 put-nibble Estrobe 5 ms 
7*0011 put-nibble Estrobe 1 ms 
°/«0011 put-nibble Estrobe 1 ms 

\ Function set for 4-bit interface; it is still in 8-bit mode. 
°/«0010 put-nibble Estrobe 1 ms 

\ Now, we should be in 4-bit interface mode. 

\ Function set for 4-bit interface , 2 display lines 5x7 font . 
wait-for-led 
%00101000 lcd-putc 

\ Increment cursor after each byte, don’t shift display, 
wait-for-led 
7*00000110 lcd-putc 
\ Display off 
wait-for-led 
°/ 0 00001000 lcd-putc 
\ Display clear 
7,00000001 lcd-putc 
5 ms 

\ End of "initialization by 
\ Enable cursor and display , 
wait-for-led 


instruct ion 
no blink . 
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134 

7o00001110 

led - 

putc 1 ms 

135 

wait -f or - 

led 


136 




137 




138 

led - emit 

( c - 

- ) \ Write the byte into 

139 

wait-f or - 

led 


140 

RShi short-del 

ay 

141 

led-putc 



142 




143 




144 

led -type 

( c-addr n -- ) \ send string 

145 

for c@+ 1 

cd - em 

it next 

146 

drop 



147 




148 




149 

main 



150 

." Begin . 

ii 


151 

led -init 



152 

cr ." led 

-init 

done . " 

153 

s" Hello 

from " 

led-type 

154 

$40 led-goto 


155 

s" FlashF 

orth 

5.0" led-type 

156 

cr ." exe 

r c i se 

done . " 

157 





memory. 
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A USING OTHER TERMINAL PROGRAMS 


A Using other terminal programs 

As discussed in Section 4, interaction with the programmed MCU is via the serial port. 
There are a number of generic terminal emulation programs that will communicate via 
a serial port. On a Linux machine the cutecom terminal program is very convenient. It 
has a line-oriented input that doesn’t send the text to the MCU until you press the enter 
key. This allows for editing of the line before committing it to the MCU and convenient 
recall of previous lines. GtkTerra is available as more conventional terminal program. 
The following images shows the GtkTerm window just after sending the content of the 
flash-led.txt hie to the PIC18F26K22. The device name of /dev/ttyUSBO refers to 
the USB-to-serial interface that was plugged one of the PC’s USB ports. It is convenient 
to start GtkTerm with the command 

$ sudo gtkterra 

and then adjust the communication settings via the Configuration —» Port menu item 
and its associated dialog window. 



There is also a send-hle capability and, importantly, the capability to set the period be¬ 
tween lines of text that are sent to the serial port so as to not overwhelm the FlashForth 
MCU. Although USB-to-serial interfaces usually implement software Xon-Xoff handshak¬ 
ing, my experience of using them with a minimal 3-wire connection (GND, RX and TX) 
has been variable. When sending large hies, an end-of-line delay of a few tens of millisec¬ 
onds has usually been found adequate, however, there have been times that a hie would 
not successfully load until the end-of-line pause was increased to 300 milliseconds. For 
GtkTerm, this setting is under the Advanced Configuration Options in the port con¬ 
figuration dialog, as shown below. This end-of-line delay makes the transfer of large hies 
slow, however, the text still scrolls past quickly but is now at a pace where it is possible to 
follow the dialog and know how well the compilation is going. Building your application 
code incrementally, with small hies, is a good thing. 
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- 

Configuration (as superuser) 


Port: 

Baud Rate: Ferity: 


|/dev/ttyUSBO 

▼ 38400 ▼ none 

:| 

Bits: 

Stopbits: Flow control: 


I s 

til 1 i| 1, Xon/Xoff 

il 



- Advanced Configuration Options 
ASCII file transfer 

End of line delay (milliseconds): 

□ Wait for this special character before passing to next line: 
RS485 half-duplex parameters (RTS signal used to send) 
Time with RTS 'on' before transmit (milliseconds): 

Time with RTS 'on' after transmit (milliseconds): 


For MacOSX, Thomas Buschhardt reports that CoolTerra is a good choice for a terminal 
application. It is available from http://freeware.the-meiers.org/. 


□ g£B m X m B © 

BP FlashForth PIC18FZ6Z0 19.01.Z015 
.words 

p++.pc@.@p.hi.d..ud..d>.d< 

d=.d0<.d0=.dinvert.dZ*.dZ/.d-.d+ 

dabs.?dnegate.dnegate.s>d.rdrop.endit.next.for 

in,.inline.repeat.while.again.until.begin.else 

then.if.until,.again,.begin,.else,.then,.if, 

not,.nc,.nz,.z,.br?.dump..s.words 

>pr..id.ms.ticks.s0.latest.state.bl 

Z-.[•].-§.;.:noname.:.].[ 

does>.postpone.create.cr.[char].(.char.' 

abort".?abort.?abort?.abort.prompt.quit.true.false 

.st.inlined.immediate.shb.interpret.'source.>in.tiu 

tib.ti#.number?.>number.ud/mod.ud*.sign?.digit? 

find. immed?. (f). on. n>c .§>+. c@+. place 

cmove.word.parse.\./string.source.user.base 

pad.hp.task.ulink.bin.hex.decimal.. 

u.r.u..sign.#>.#s.#.>digit.<# 

hold.up.min.max.?negate.tuck.nip./ 

u*/mod.u/.*.u/mod.um/mod.um*.'key?.'key 

■pmit- n? 4- ri4. nri ni n@ r->n I rr»r 


usbserial-ftDIGW15 / 9600 8-N-1 ft TX (j RTS & DTR • DCD 

Connected 19:07:18 # RX (J CTS ft DSR ft Rl 


































